# ElevenLabs Documentation

> Explore our docs and guides to integrate ElevenLabs

{/* Light mode wave */}

<div id="overview-wave">
  <ElevenLabsWaveform color="blue" />
</div>

{/* Dark mode wave */}

<div id="overview-wave">
  <ElevenLabsWaveform color="gray" />
</div>

<div id="agents-cards">
  <a href="/docs/creative-platform/overview">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/12097a437e55f60c199946cf59c9528eb8349d110142394833d67fe93b50e68d/assets/images/overview/voice-library-bg.webp" alt="" />
    </div>

    <div>
      <h3>
        ElevenCreative
      </h3>

      <p>
        Learn how to use the ElevenCreative platform with step-by-step guides
      </p>
    </div>
  </a>

  <a href="/docs/agents-platform/overview">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/17a81505a62493491ead763b307b1e854825a0da67ab1a1d86b41b57ad87bc73/assets/images/agents/agents-overview-integrate.png" alt="" />
    </div>

    <div>
      <h3>
        ElevenAgents
      </h3>

      <p>
        Learn how to build, launch, and scale agents with ElevenLabs
      </p>
    </div>
  </a>

  <a href="/docs/developers/quickstart">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/002b2432fa6ab18befc9f1a6e7fadf348f46506a5a5a72a2358ba1e7f92d8ded/assets/images/overview/scribe-code-bg.webp" alt="" />
    </div>

    <div>
      <h3>
        ElevenAPI
      </h3>

      <p>
        Learn how to integrate with the ElevenLabs APIwith examples and tutorials
      </p>
    </div>
  </a>
</div>

## Meet the models

<CardGroup cols={2} rows={2}>
  <Card title="Eleven v3" href="/docs/overview/models#eleven-v3">
    Our most emotionally rich, expressive speech synthesis model

    <div>
      <div>
        Dramatic delivery and performance
      </div>

      <div>
        70+ languages supported
      </div>

      <div>
        5,000 character limit
      </div>

      <div>
        Support for natural multi-speaker dialogue
      </div>
    </div>
  </Card>

  <Card title="Eleven Multilingual v2" href="/docs/overview/models#multilingual-v2">
    Lifelike, consistent quality speech synthesis model

    <div>
      <div>
        Natural-sounding output
      </div>

      <div>
        29 languages supported
      </div>

      <div>
        10,000 character limit
      </div>

      <div>
        Most stable on long-form generations
      </div>
    </div>
  </Card>

  <Card title="Eleven Flash v2.5" href="/docs/overview/models#flash-v25">
    Our fast, affordable speech synthesis model

    <div>
      <div>
        Ultra-low latency (~75ms†)
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Faster model, 50% lower price per character
      </div>
    </div>
  </Card>

  <Card title="Eleven Turbo v2.5" href="/docs/overview/models#turbo-v25">
    High quality, low-latency model with a good balance of quality and speed

    <div>
      <div>
        High quality voice generation
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Low latency (~250ms-300ms†), 50% lower price per character
      </div>
    </div>
  </Card>
</CardGroup>

<CardGroup cols={2} rows={1}>
  <Card title="Scribe v2" href="/docs/overview/models#scribe-v2">
    State-of-the-art speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Keyterm prompting, up to 100 terms
      </div>

      <div>
        Entity detection, up to 56
      </div>

      <div>
        Precise word-level timestamps
      </div>

      <div>
        Speaker diarization, up to 32 speakers
      </div>

      <div>
        Dynamic audio tagging
      </div>

      <div>
        Smart language detection
      </div>
    </div>
  </Card>

  <Card title="Scribe v2 Realtime" href="/docs/overview/models#scribe-v2-realtime">
    Real-time speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Real-time transcription
      </div>

      <div>
        Low latency (~150ms†)
      </div>

      <div>
        Precise word-level timestamps
      </div>
    </div>
  </Card>
</CardGroup>

<div>
  <div>
    <a href="/docs/overview/models">
      Explore all
    </a>
  </div>
</div>

<small>
  † Excluding application & network latency
</small>

## Browse by capability

<CardGroup cols={3}>
  <Card href="/docs/overview/capabilities/text-to-speech" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/696de2d6ea9525ec2924c8bdd14d9f2a1657df3fac57296ea1493ed880c3c471/assets/icons/tts.svg">
    <div>
      <div>
        <div>
          Text to Speech
        </div>

        <p>
          Convert text into lifelike speech
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/speech-to-text" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3e83584349e77b9051992231686d684fa36b1297419f7b307f8d18db9f8af63b/assets/icons/stt.svg">
    <div>
      <div>
        <div>
          Speech to Text
        </div>

        <p>
          Transcribe spoken audio into text
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/music" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/067501e7571cee7a21b69890118527cce311809dfd041683bcc6e7ad6bbd5b03/assets/icons/music.svg">
    <div>
      <div>
        <div>
          Music
        </div>

        <p>
          Generate music from text
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/text-to-dialogue" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/effa86ad1daea8205bb18d56bbc50a6c2bd5f73c889f730fcf85a5d479110808/assets/icons/ttd.svg">
    <div>
      <div>
        <div>
          Text to Dialogue
        </div>

        <p>
          Create natural-sounding dialogue from text
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/image-video" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/676300f3f5d62055afd78aa54e253ad52ff4baf42d04a2ca4675d5542e50d814/assets/icons/image-and-video.svg">
    <div>
      <div>
        <div>
          Image & Video
        </div>

        <p>
          Generate images and videos from text
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/voice-changer" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7df7da1ff4f05f8af90cb13f3871eafb7865cb586b2e9e54b1767ff882dba49e/assets/icons/voice-changer.svg">
    <div>
      <div>
        <div>
          Voice changer
        </div>

        <p>
          Modify and transform voices
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/voice-isolator" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/aa6b1b7b79ac7a58b74139ee58b8df80d15081558e25670f64bde8def0408b13/assets/icons/voice-isolator.svg">
    <div>
      <div>
        <div>
          Voice isolator
        </div>

        <p>
          Isolate voices from background noise
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/dubbing" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/77d8c519257eb198dd8c1be0c00e24edfbbf36bf99d5edcc5dcf5598c8e9ae36/assets/icons/dubbing.svg">
    <div>
      <div>
        <div>
          Dubbing
        </div>

        <p>
          Dub audio and videos seamlessly
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/sound-effects" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/daa1351dc78940a6fa4233106fedd3e03bf7eeba575ce316bca721ba2ee95c0e/assets/icons/sfx.svg">
    <div>
      <div>
        <div>
          Sound effects
        </div>

        <p>
          Create cinematic sound effects
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/voices" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b834427deaf202a6c9126c08d7e9a128df0ab0d707882a1743d6fde9aeb5551/assets/icons/voices.svg">
    <div>
      <div>
        <div>
          Voices
        </div>

        <p>
          Clone and design custom voices
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/voice-remixing" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d4421ae4f799fe5d31c67c43e12a3445eef9cb3db724a5a83000fb97a263a050/assets/icons/remix-voice.svg">
    <div>
      <div>
        <div>
          Voice Remixing
        </div>

        <p>
          Transform and enhance existing voices
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/overview/capabilities/forced-alignment" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/297bc4494e935d84aa71f8da42a738f6b705905523327acbc7e0ac2dcaf28016/assets/icons/forced-alignment.svg">
    <div>
      <div>
        <div>
          Forced Alignment
        </div>

        <p>
          Align text to audio
        </p>
      </div>
    </div>
  </Card>

  <Card href="/docs/agents-platform/overview" icon="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/adb7775de5efe649b1563f11fd232ad250a83b9706b26bcfd1055a959e159031/assets/icons/agents-platform.svg">
    <div>
      <div>
        <div>
          ElevenAgents
        </div>

        <p>
          Deploy intelligent voice agents
        </p>
      </div>
    </div>
  </Card>
</CardGroup>


# Models

> Learn about the models that power the ElevenLabs API.

## Flagship models

### Text to Speech

<CardGroup cols={2} rows={2}>
  <Card title="Eleven v3" href="/docs/overview/models#eleven-v3">
    Our most emotionally rich, expressive speech synthesis model

    <div>
      <div>
        Dramatic delivery and performance
      </div>

      <div>
        70+ languages supported
      </div>

      <div>
        5,000 character limit
      </div>

      <div>
        Support for natural multi-speaker dialogue
      </div>
    </div>
  </Card>

  <Card title="Eleven Multilingual v2" href="/docs/overview/models#multilingual-v2">
    Lifelike, consistent quality speech synthesis model

    <div>
      <div>
        Natural-sounding output
      </div>

      <div>
        29 languages supported
      </div>

      <div>
        10,000 character limit
      </div>

      <div>
        Most stable on long-form generations
      </div>
    </div>
  </Card>

  <Card title="Eleven Flash v2.5" href="/docs/overview/models#flash-v25">
    Our fast, affordable speech synthesis model

    <div>
      <div>
        Ultra-low latency (~75ms†)
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Faster model, 50% lower price per character
      </div>
    </div>
  </Card>

  <Card title="Eleven Turbo v2.5" href="/docs/overview/models#turbo-v25">
    High quality, low-latency model with a good balance of quality and speed

    <div>
      <div>
        High quality voice generation
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Low latency (~250ms-300ms†), 50% lower price per character
      </div>
    </div>
  </Card>
</CardGroup>

### Speech to Text

<CardGroup cols={2} rows={1}>
  <Card title="Scribe v2" href="/docs/overview/models#scribe-v2">
    State-of-the-art speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Keyterm prompting, up to 100 terms
      </div>

      <div>
        Entity detection, up to 56
      </div>

      <div>
        Precise word-level timestamps
      </div>

      <div>
        Speaker diarization, up to 32 speakers
      </div>

      <div>
        Dynamic audio tagging
      </div>

      <div>
        Smart language detection
      </div>
    </div>
  </Card>

  <Card title="Scribe v2 Realtime" href="/docs/overview/models#scribe-v2-realtime">
    Real-time speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Real-time transcription
      </div>

      <div>
        Low latency (~150ms†)
      </div>

      <div>
        Precise word-level timestamps
      </div>
    </div>
  </Card>
</CardGroup>

### Music

<CardGroup cols={1} rows={1}>
  <Card title="Eleven Music" href="/docs/overview/models#eleven-music">
    Studio-grade music with natural language prompts in any style

    <div>
      <div>
        Complete control over genre, style, and structure
      </div>

      <div>
        Vocals or just instrumental
      </div>

      <div>
        Multilingual, including English, Spanish, German, Japanese and more
      </div>

      <div>
        Edit the sound and lyrics of individual sections or the whole song
      </div>
    </div>
  </Card>
</CardGroup>

<div>
  <div>
    <a href="https://elevenlabs.io/pricing/api">
      Pricing
    </a>
  </div>
</div>

## Models overview

The ElevenLabs API offers a range of audio models optimized for different use cases, quality levels, and performance requirements.

| Model ID                     | Description                                                                              | Languages                                                                                                                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eleven_v3`                  | Human-like and expressive speech generation                                              | [70+ languages](/docs/overview/models#supported-languages)                                                                                                                                      |
| `eleven_ttv_v3`              | Human-like and expressive voice design model (Text to Voice)                             | [70+ languages](/docs/overview/models#supported-languages)                                                                                                                                      |
| `eleven_multilingual_v2`     | Our most lifelike model with rich emotional expression                                   | `en`, `ja`, `zh`, `de`, `hi`, `fr`, `ko`, `pt`, `it`, `es`, `id`, `nl`, `tr`, `fil`, `pl`, `sv`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `ru`                   |
| `eleven_flash_v2_5`          | Ultra-fast model optimized for real-time use (\~75ms†)                                   | All `eleven_multilingual_v2` languages plus: `hu`, `no`, `vi`                                                                                                                                   |
| `eleven_flash_v2`            | Ultra-fast model optimized for real-time use (\~75ms†)                                   | `en`                                                                                                                                                                                            |
| `eleven_turbo_v2_5`          | High quality, low-latency model with a good balance of quality and speed (\~250ms-300ms) | `en`, `ja`, `zh`, `de`, `hi`, `fr`, `ko`, `pt`, `it`, `es`, `id`, `nl`, `tr`, `fil`, `pl`, `sv`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `ru`, `hu`, `no`, `vi` |
| `eleven_turbo_v2`            | High quality, low-latency model with a good balance of quality and speed (\~250ms-300ms) | `en`                                                                                                                                                                                            |
| `eleven_multilingual_sts_v2` | State-of-the-art multilingual voice changer model (Speech to Speech)                     | `en`, `ja`, `zh`, `de`, `hi`, `fr`, `ko`, `pt`, `it`, `es`, `id`, `nl`, `tr`, `fil`, `pl`, `sv`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `ru`                   |
| `eleven_multilingual_ttv_v2` | State-of-the-art multilingual voice designer model (Text to Voice)                       | `en`, `ja`, `zh`, `de`, `hi`, `fr`, `ko`, `pt`, `it`, `es`, `id`, `nl`, `tr`, `fil`, `pl`, `sv`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `ru`                   |
| `eleven_english_sts_v2`      | English-only voice changer model (Speech to Speech)                                      | `en`                                                                                                                                                                                            |
| `scribe_v2_realtime`         | Real-time speech recognition model                                                       | [90+ languages](/docs/overview/capabilities/speech-to-text#supported-languages)                                                                                                                 |
| `scribe_v2`                  | State-of-the-art speech recognition model                                                | [90+ languages](/docs/overview/capabilities/speech-to-text#supported-languages)                                                                                                                 |
| `scribe_v1`                  | State-of-the-art speech recognition. Outclassed by v2 models                             | [90+ languages](/docs/overview/capabilities/speech-to-text#supported-languages)                                                                                                                 |
| `eleven_text_to_sound_v2`    | Sound effects generation from text prompts                                               | N/A                                                                                                                                                                                             |
| `music_v1`                   | Studio-grade music generation from text prompts                                          | `en`, `es`, `de`, `ja`, and more                                                                                                                                                                |

<small>
  † Excluding application & network latency
</small>

### Deprecated models

<Error>
  The `eleven_monolingual_v1` and `eleven_multilingual_v1` models are deprecated and will be removed in the future. Please migrate to newer models for continued service.
</Error>

| Model ID                 | Description                                          | Languages                                      | Replacement model suggestion |
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------- | ---------------------------- |
| `eleven_monolingual_v1`  | First generation TTS model (outclassed by v2 models) | `en`                                           | `eleven_multilingual_v2`     |
| `eleven_multilingual_v1` | First multilingual model (outclassed by v2 models)   | `en`, `fr`, `de`, `hi`, `it`, `pl`, `pt`, `es` | `eleven_multilingual_v2`     |

## Eleven v3

Eleven v3 is our latest and most advanced speech synthesis model. It is a state-of-the-art model that produces natural, life-like speech with high emotional range and contextual understanding across multiple languages.

This model works well in the following scenarios:

* **Character Discussions**: Excellent for audio experiences with multiple characters that interact with each other.
* **Audiobook Production**: Perfect for long-form narration with complex emotional delivery.
* **Emotional Dialogue**: Generate natural, lifelike dialogue with high emotional range and contextual understanding.

With Eleven v3 comes a new Text to Dialogue API, which allows you to generate natural, lifelike dialogue with high emotional range and contextual understanding across multiple languages. Eleven v3 can also be used with the Text to Speech API to generate natural, lifelike speech with high emotional range and contextual understanding across multiple languages.

Read more about the Text to Dialogue API [here](/docs/overview/capabilities/text-to-dialogue).

### Supported languages

The Eleven v3 model supports 70+ languages, including:

*Afrikaans (afr), Arabic (ara), Armenian (hye), Assamese (asm), Azerbaijani (aze), Belarusian (bel), Bengali (ben), Bosnian (bos), Bulgarian (bul), Catalan (cat), Cebuano (ceb), Chichewa (nya), Croatian (hrv), Czech (ces), Danish (dan), Dutch (nld), English (eng), Estonian (est), Filipino (fil), Finnish (fin), French (fra), Galician (glg), Georgian (kat), German (deu), Greek (ell), Gujarati (guj), Hausa (hau), Hebrew (heb), Hindi (hin), Hungarian (hun), Icelandic (isl), Indonesian (ind), Irish (gle), Italian (ita), Japanese (jpn), Javanese (jav), Kannada (kan), Kazakh (kaz), Kirghiz (kir), Korean (kor), Latvian (lav), Lingala (lin), Lithuanian (lit), Luxembourgish (ltz), Macedonian (mkd), Malay (msa), Malayalam (mal), Mandarin Chinese (cmn), Marathi (mar), Nepali (nep), Norwegian (nor), Pashto (pus), Persian (fas), Polish (pol), Portuguese (por), Punjabi (pan), Romanian (ron), Russian (rus), Serbian (srp), Sindhi (snd), Slovak (slk), Slovenian (slv), Somali (som), Spanish (spa), Swahili (swa), Swedish (swe), Tamil (tam), Telugu (tel), Thai (tha), Turkish (tur), Ukrainian (ukr), Urdu (urd), Vietnamese (vie), Welsh (cym).*

## Multilingual v2

Eleven Multilingual v2 is our most advanced, emotionally-aware speech synthesis model. It produces natural, lifelike speech with high emotional range and contextual understanding across multiple languages.

The model delivers consistent voice quality and personality across all supported languages while maintaining the speaker's unique characteristics and accent.

This model excels in scenarios requiring high-quality, emotionally nuanced speech:

* **Character Voiceovers**: Ideal for gaming and animation due to its emotional range.
* **Professional Content**: Well-suited for corporate videos and e-learning materials.
* **Multilingual Projects**: Maintains consistent voice quality across language switches.
* **Stable Quality**: Produces consistent, high-quality audio output.

While it has a higher latency & cost per character than Flash models, it delivers superior quality for projects where lifelike speech is important.

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

## Flash v2.5

Eleven Flash v2.5 is our fastest speech synthesis model, designed for real-time applications and Agents Platform. It delivers high-quality speech with ultra-low latency (\~75ms†) across 32 languages.

The model balances speed and quality, making it ideal for interactive applications while maintaining natural-sounding output and consistent voice characteristics across languages.

This model is particularly well-suited for:

* **Agents Platform**: Perfect for real-time voice agents and chatbots.
* **Interactive Applications**: Ideal for games and applications requiring immediate response.
* **Large-Scale Processing**: Efficient for bulk text-to-speech conversion.

With its lower price point and 75ms latency, Flash v2.5 is the cost-effective option for anyone needing fast, reliable speech synthesis across multiple languages.

Flash v2.5 supports 32 languages - all languages from v2 models plus:

*Hungarian, Norwegian & Vietnamese*

<small>
  † Excluding application & network latency
</small>

### Considerations

<AccordionGroup>
  <Accordion title="Text normalization with numbers">
    When using Flash v2.5, numbers aren't normalized by default in a way you might expect. For example, phone numbers might be read out in way that isn't clear for the user. Dates and currencies are affected in a similar manner.

    By default, normalization is disabled for Flash v2.5 to maintain the low latency. However, Enterprise customers can now enable text normalization for v2.5 models by setting the `apply_text_normalization` parameter to "on" in your request.

    The Multilingual v2 model does a better job of normalizing numbers, so we recommend using it for phone numbers and other cases where number normalization is important.

    For low-latency or Agents Platform applications, best practice is to have your LLM [normalize the text](/docs/overview/capabilities/text-to-speech/best-practices#text-normalization) before passing it to the TTS model, or use the `apply_text_normalization` parameter (Enterprise plans only for v2.5 models).
  </Accordion>
</AccordionGroup>

## Turbo v2.5

Eleven Turbo v2.5 is our high-quality, low-latency model with a good balance of quality and speed.

This model is an ideal choice for all scenarios where you'd use Flash v2.5, but where you're willing to trade off latency for higher quality voice generation.

## Model selection guide

<AccordionGroup>
  <Accordion title="Requirements">
    <CardGroup cols={1}>
      <Card title="Quality">
        Use `eleven_multilingual_v2`

        Best for high-fidelity audio output with rich emotional expression
      </Card>

      <Card title="Low-latency">
        Use Flash models

        Optimized for real-time applications (\~75ms latency)
      </Card>

      <Card title="Multilingual">
        Use either either `eleven_multilingual_v2` or `eleven_flash_v2_5`

        Both support up to 32 languages
      </Card>

      <Card title="Balanced">
        Use `eleven_turbo_v2_5`

        Good balance between quality and speed
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Use case">
    <CardGroup cols={1}>
      <Card title="Content creation">
        Use `eleven_multilingual_v2`

        Ideal for professional content, audiobooks & video narration.
      </Card>

      <Card title="Agents Platform">
        Use `eleven_flash_v2_5`, `eleven_flash_v2`, `eleven_multilingual_v2`, `eleven_turbo_v2_5` or `eleven_turbo_v2`

        Perfect for real-time conversational applications
      </Card>

      <Card title="Voice changer">
        Use `eleven_multilingual_sts_v2`

        Specialized for Speech-to-Speech conversion
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Character limits

The maximum number of characters supported in a single text-to-speech request varies by model.

| Model ID                 | Character limit | Approximate audio duration |
| ------------------------ | --------------- | -------------------------- |
| `eleven_v3`              | 5,000           | \~5 minutes                |
| `eleven_flash_v2_5`      | 40,000          | \~40 minutes               |
| `eleven_flash_v2`        | 30,000          | \~30 minutes               |
| `eleven_turbo_v2_5`      | 40,000          | \~40 minutes               |
| `eleven_turbo_v2`        | 30,000          | \~30 minutes               |
| `eleven_multilingual_v2` | 10,000          | \~10 minutes               |
| `eleven_multilingual_v1` | 10,000          | \~10 minutes               |
| `eleven_english_sts_v2`  | 10,000          | \~10 minutes               |
| `eleven_english_sts_v1`  | 10,000          | \~10 minutes               |

<Note>
  For longer content, consider splitting the input into multiple requests.
</Note>

## Scribe v2

Scribe v2 is our state-of-the-art speech recognition model designed for accurate transcription across 90+ languages. It provides precise word-level timestamps and advanced features like speaker diarization and dynamic audio tagging.

This model excels in scenarios requiring accurate speech-to-text conversion:

* **Transcription Services**: Perfect for converting audio/video content to text
* **Meeting Documentation**: Ideal for capturing and documenting conversations
* **Content Analysis**: Well-suited for audio content processing and analysis
* **Multilingual Recognition**: Supports accurate transcription across 90+ languages

Key features:

* Accurate transcription with word-level timestamps
* Speaker diarization for multi-speaker audio
* Dynamic audio tagging for enhanced context
* Support for 90+ languages
* Entity detection
* Keyterm prompting

Read more about Scribe v2 [here](/docs/overview/capabilities/speech-to-text).

## Scribe v2 Realtime

Scribe v2 Realtime, our fastest and most accurate live speech recognition model, delivers state-of-the-art accuracy in over 90 languages with an ultra-low 150ms of latency.

This model excels in conversational use cases:

* **Live meeting transcription**: Perfect for realtime transcription
* **AI Agents**: Ideal for live conversations
* **Multilingual Recognition**: Supports accurate transcription across 90+ languages with automatic language recognition

Key features:

* Ultra-low latency: Get partial transcriptions in \~150 milliseconds
* Streaming support: Send audio in chunks while receiving transcripts in real-time
* Multiple audio formats: Support for PCM (8kHz to 48kHz) and μ-law encoding
* Voice Activity Detection (VAD): Automatic speech segmentation based on silence detection
* Manual commit control: Full control over when to finalize transcript segments

Read more about Scribe v2 Realtime [here](/docs/overview/capabilities/speech-to-text).

## Eleven Music

Eleven Music is our studio-grade music generation model. It allows you to generate music with natural language prompts in any style.

This model is excellent for the following scenarios:

* **Game Soundtracks**: Create immersive soundtracks for games
* **Podcast Backgrounds**: Enhance podcasts with professional music
* **Marketing**: Add background music to ad reels

Key features:

* Complete control over genre, style, and structure
* Vocals or just instrumental
* Multilingual, including English, Spanish, German, Japanese and more
* Edit the sound and lyrics of individual sections or the whole song

Read more about Eleven Music [here](/docs/overview/capabilities/music).

## Concurrency and priority

Your subscription plan determines how many requests can be processed simultaneously and the priority level of your requests in the queue.
Speech to Text has an elevated concurrency limit.
Once the concurrency limit is met, subsequent requests are processed in a queue alongside lower-priority requests.
In practice this typically only adds \~50ms of latency.

| Plan       | Concurrency Limit<br /> (Multilingual v2) | Concurrency Limit<br /> (Turbo & Flash) | STT Concurrency Limit | Realtime STT Concurrency limit | Music Concurrency limit | Priority level |
| ---------- | ----------------------------------------- | --------------------------------------- | --------------------- | ------------------------------ | ----------------------- | -------------- |
| Free       | 2                                         | 4                                       | 8                     | 6                              | 0                       | 3              |
| Starter    | 3                                         | 6                                       | 12                    | 9                              | 2                       | 4              |
| Creator    | 5                                         | 10                                      | 20                    | 15                             | 2                       | 5              |
| Pro        | 10                                        | 20                                      | 40                    | 30                             | 2                       | 5              |
| Scale      | 15                                        | 30                                      | 60                    | 45                             | 5                       | 5              |
| Business   | 15                                        | 30                                      | 60                    | 45                             | 5                       | 5              |
| Enterprise | Elevated                                  | Elevated                                | Elevated              | Elevated                       | Highest                 | 6              |

<Note>
  Startup grants recipients receive Scale level benefits.
</Note>

The response headers include `current-concurrent-requests` and `maximum-concurrent-requests` which you can use to monitor your concurrency.

### API requests per minute vs concurrent requests

It's important to understand that **API requests per minute** and **concurrent requests** are different metrics that depend on your usage patterns.

API requests per minute can be different from concurrent requests since it depends on the length of time for each request and how the requests are batched.

**Example 1: Spaced requests**
If you had 180 requests per minute that each took 1 second to complete and you sent them each 0.33 seconds apart, the max concurrent requests would be 3 and the average would be 3 since there would always be 3 in flight.

**Example 2: Batched requests**
However, if you had a different usage pattern such as 180 requests per minute that each took 3 seconds to complete but all fired at once, the max concurrent requests would be 180 and the average would be 9 (first 3 seconds of the minute saw 180 requests at once, final 57 seconds saw 0 requests).

Since our system cares about concurrency, requests per minute matter less than how long each of the requests take and the pattern of when they are sent.

How endpoint requests are made impacts concurrency limits:

* With HTTP, each request counts individually toward your concurrency limit.
* With a WebSocket, only the time where our model is generating audio counts towards your concurrency limit, this means a for most of the time an open websocket doesn't count towards your concurrency limit at all.

### Understanding concurrency limits

The concurrency limit associated with your plan should not be interpreted as the maximum number of simultaneous conversations, phone calls character voiceovers, etc that can be handled at once.
The actual number depends on several factors, including the specific AI voices used and the characteristics of the use case.

As a general rule of thumb, a concurrency limit of 5 can typically support up to approximately 100 simultaneous audio broadcasts.

This is because of the speed it takes for audio to be generated relative to the time it takes for the TTS request to be processed.
The diagram below is an example of how 4 concurrent calls with different users can be facilitated while only hitting 2 concurrent requests.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/dcc5e3bd18993a9f862bd526f3dc1b32cfa89003a58ded6f4f6a7bda1bd5a2ea/assets/images/product-guides/speech-to-text/tts-concurrency.png" alt="Concurrency limits" />
</Frame>

<AccordionGroup>
  <Accordion title="Building AI Voice Agents">
    Where TTS is used to facilitate dialogue, a concurrency limit of 5 can support about 100 broadcasts for balanced conversations between AI agents and human participants.

    For use cases in which the AI agent speaks less frequently than the human, such as customer support interactions, more than 100 simultaneous conversations could be supported.
  </Accordion>

  <Accordion title="Character voiceovers">
    Generally, more than 100 simultaneous character voiceovers can be supported for a concurrency limit of 5.

    The number can vary depending on the character’s dialogue frequency, the length of pauses, and in-game actions between lines.
  </Accordion>

  <Accordion title="Live Dubbing">
    Concurrent dubbing streams generally follow the provided heuristic.

    If the broadcast involves periods of conversational pauses (e.g. because of a soundtrack, visual scenes, etc), more simultaneous dubbing streams than the suggestion may be possible.
  </Accordion>
</AccordionGroup>

If you exceed your plan's concurrency limits at any point and you are on the Enterprise plan, model requests may still succeed, albeit slower, on a best efforts basis depending on available capacity.

<Note>
  To increase your concurrency limit & queue priority, [upgrade your subscription
  plan](https://elevenlabs.io/pricing/api).

  Enterprise customers can request a higher concurrency limit by contacting their account manager.
</Note>

### Scale testing concurrency limits

Scale testing can be useful to identify client side scaling issues and to verify concurrency limits are set correctly for your usecase.

It is heavily recommended to test end-to-end workflows as close to real world usage as possible, simulating and measuring how many users can be supported is the recommended methodology for achieving this. It is important to:

* Simulate users, not raw requests
* Simulate typical user behavior such as waiting for audio playback, user speaking or transcription to finish before making requests
* Ramp up the number of users slowly over a period of minutes
* Introduce randomness to request timings and to the size of requests
* Capture latency metrics and any returned error codes from the API

For example, to test an agent system designed to support 100 simultaneous conversations you would create up to 100 individual "users" each simulating a conversation. Conversations typically consist of a repeating cycle of \~10 seconds of user talking, followed by the TTS API call for \~150 characters, followed by \~10 seconds of audio playback to the user. Therefore, each user should follow the pattern of making a websocket Text-to-Speech API call for 150 characters of text every 20 seconds, with a small amount of randomness introduced to the wait period and the number of characters requested. The test would consist of spawning one user per second until 100 exist and then testing for 10 minutes in total to test overall stability.

<AccordionGroup>
  <Accordion title="Scale testing script example">
    This example uses [locust](https://locust.io/) as the testing framework with direct API calls to the ElevenLabs API.

    It follows the example listed above, testing a conversational agent system with each user sending 1 request every 20 seconds.

    <CodeBlocks>
      ```python title="Python" {12}
      import json
      import random
      import time
      import gevent
      import locust
      from locust import User, task, events, constant_throughput
      import websocket

      # Averages up to 10 seconds of audio when played, depends on the voice speed
      DEFAULT_TEXT = (
          "Hello, this is a test message. I am testing if a long input will cause issues for the model "
          "like this sentence. "
      )

      TEXT_ARRAY = [
          "Hello.",
          "Hello, this is a test message.",
          DEFAULT_TEXT,
          DEFAULT_TEXT * 2,
          DEFAULT_TEXT * 3
      ]

      # Custom command line arguments
      @events.init_command_line_parser.add_listener
      def on_parser_init(parser):
          parser.add_argument("--api-key", default="YOUR_API_KEY", help="API key for authentication")
          parser.add_argument("--encoding", default="mp3_22050_32", help="Encoding")
          parser.add_argument("--text", default=DEFAULT_TEXT, help="Text to use")
          parser.add_argument("--use-text-array", default="false", help="Text to use")
          parser.add_argument("--voice-id", default="aria", help="Text to use")


      class WebSocketTTSUser(User):
          # Each user will send a request every 20 seconds, regardless of how long each request takes
          wait_time = constant_throughput(0.05)

          def __init__(self, *args, **kwargs):
              super().__init__(*args, **kwargs)
              self.api_key = self.environment.parsed_options.api_key
              self.voice_id = self.environment.parsed_options.voice_id
              self.text = self.environment.parsed_options.text
              self.encoding = self.environment.parsed_options.encoding
              self.use_text_array = self.environment.parsed_options.use_text_array
              if self.use_text_array:
                  self.text = random.choice(TEXT_ARRAY)
              self.all_recieved = False

          @task
          def tts_task(self):
              # Do jitter waiting of up to 1 second
              # Users appear to be spawned every second so this ensures requests are not aligned
              gevent.sleep(random.random())

              max_wait_time = 10

              # Connection details
              uri = f"{self.environment.host}/v1/text-to-speech/{self.voice_id}/stream-input?auto_mode=true&output_format={self.encoding}"
              headers = {"xi-api-key": self.api_key}

              ws = None
              self.all_recieved = False
              try:
                  init_msg = {"text": " "}
                  # Use proper header format for websocket - this is case sensitive!
                  ws = websocket.create_connection(uri, header=headers)
                  ws.send(json.dumps(init_msg))

                  # Start measuring after websocket initiated but before any messages are sent
                  send_request_time = time.perf_counter()
                  ws.send(json.dumps({"text": self.text}))

                  # Send to flush and receive the audio
                  ws.send(json.dumps({"text": ""}))

                  def _receive():
                      t_first_response = None
                      audio_size = 0
                      try:
                          while True:
                              # Wait up to 10 seconds for a response
                              ws.settimeout(max_wait_time)
                              response = ws.recv()
                              response_data = json.loads(response)

                              if "audio" in response_data and response_data["audio"]:
                                  audio_size = audio_size + len(response_data["audio"])

                              if t_first_response is None:
                                  t_first_response = time.perf_counter()
                                  first_byte_ms = (
                                      t_first_response - send_request_time
                                  ) * 1000
                                  if audio_size is None:
                                      # The first response should always have audio
                                      locust.events.request.fire(
                                          request_type="websocket",
                                          name="Bad Response (no audio)",
                                          response_time=first_byte_ms,
                                          response_length=audio_size,
                                          exception=Exception("Response has no audio"),
                                      )
                                      break

                              if "isFinal" in response_data and response_data["isFinal"]:
                                  # Fire this event once finished streaming, but report the important TTFB metric
                                  locust.events.request.fire(
                                      request_type="websocket",
                                      name="TTS Stream Success (First Byte)",
                                      response_time=first_byte_ms,
                                      response_length=audio_size,
                                      exception=None,
                                  )
                                  break

                      except websocket.WebSocketTimeoutException:
                          locust.events.request.fire(
                              request_type="websocket",
                              name="TTS Stream Timeout",
                              response_time=max_wait_time * 1000,
                              response_length=audio_size,
                              exception=Exception("Timeout waiting for response"),
                          )
                      except Exception as e:
                          # Typically JSON decode error if the server returns HTTP backoff error
                          locust.events.request.fire(
                              request_type="websocket",
                              name="TTS Stream Failure",
                              response_time=0,
                              response_length=0,
                              exception=e,
                          )
                      finally:
                          self.all_recieved = True

                  gevent.spawn(_receive)

                  # Sleep until recieved so new tasks aren't spawned
                  while not self.all_recieved:
                      gevent.sleep(1)

              except websocket.WebSocketTimeoutException:
                  locust.events.request.fire(
                      request_type="websocket",
                      name="TTS Stream Timeout",
                      response_time=max_wait_time * 1000,
                      response_length=0,
                      exception=Exception("Timeout waiting for response"),
                  )
              except Exception as e:
                  locust.events.request.fire(
                      request_type="websocket",
                      name="TTS Stream Failure",
                      response_time=0,
                      response_length=0,
                      exception=e,
                  )
              finally:
                  # Try and close the websocket gracefully
                  try:
                      if ws:
                          ws.close()
                  except Exception:
                      pass

      ```
    </CodeBlocks>
  </Accordion>
</AccordionGroup>


# Text to Speech

> Learn how to turn text into lifelike spoken audio with ElevenLabs.

## Overview

ElevenLabs [Text to Speech (TTS)](/docs/api-reference/text-to-speech/convert) API turns text into lifelike audio with nuanced intonation, pacing and emotional awareness. [Our models](/docs/overview/models) adapt to textual cues across 32 languages and multiple voice styles and can be used to:

* Narrate global media campaigns & ads
* Produce audiobooks in multiple languages with complex emotional delivery
* Stream real-time audio from text

Listen to a sample:

<elevenlabs-audio-player audio-title="George" audio-src="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/george.mp3" />

Explore our [voice library](https://elevenlabs.io/app/voice-library) to find the perfect voice for your project.

<Warning>
  The voice library is not available via the API to free tier users.
</Warning>

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/playground/text-to-speech">
    Step-by-step guide for using text to speech in ElevenLabs.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/quickstart">
    Learn how to integrate text to speech into your application.
  </Card>
</CardGroup>

### Voice quality

For real-time applications, Flash v2.5 provides ultra-low 75ms latency, while Multilingual v2 delivers the highest quality audio with more nuanced expression.

<CardGroup cols={2} rows={2}>
  <Card title="Eleven v3" href="/docs/overview/models#eleven-v3">
    Our most emotionally rich, expressive speech synthesis model

    <div>
      <div>
        Dramatic delivery and performance
      </div>

      <div>
        70+ languages supported
      </div>

      <div>
        5,000 character limit
      </div>

      <div>
        Support for natural multi-speaker dialogue
      </div>
    </div>
  </Card>

  <Card title="Eleven Multilingual v2" href="/docs/overview/models#multilingual-v2">
    Lifelike, consistent quality speech synthesis model

    <div>
      <div>
        Natural-sounding output
      </div>

      <div>
        29 languages supported
      </div>

      <div>
        10,000 character limit
      </div>

      <div>
        Most stable on long-form generations
      </div>
    </div>
  </Card>

  <Card title="Eleven Flash v2.5" href="/docs/overview/models#flash-v25">
    Our fast, affordable speech synthesis model

    <div>
      <div>
        Ultra-low latency (~75ms†)
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Faster model, 50% lower price per character
      </div>
    </div>
  </Card>

  <Card title="Eleven Turbo v2.5" href="/docs/overview/models#turbo-v25">
    High quality, low-latency model with a good balance of quality and speed

    <div>
      <div>
        High quality voice generation
      </div>

      <div>
        32 languages supported
      </div>

      <div>
        40,000 character limit
      </div>

      <div>
        Low latency (~250ms-300ms†), 50% lower price per character
      </div>
    </div>
  </Card>
</CardGroup>

<div>
  <div>
    [Explore all](/docs/overview/models)
  </div>
</div>

### Voice options

ElevenLabs offers thousands of voices across 32 languages through multiple creation methods:

* [Voice library](/docs/overview/capabilities/voices) with 3,000+ community-shared voices
* [Professional voice cloning](/docs/overview/capabilities/voices#cloned) for highest-fidelity replicas
* [Instant voice cloning](/docs/overview/capabilities/voices#cloned) for quick voice replication
* [Voice design](/docs/overview/capabilities/voices#voice-design) to generate custom voices from text descriptions

Learn more about our [voice options](/docs/overview/capabilities/voices).

### Supported formats

The default response format is "mp3", but other formats like "PCM", & "μ-law" are available.

* **MP3**
  * Sample rates: 22.05kHz - 44.1kHz
  * Bitrates: 32kbps - 192kbps
  * 22.05kHz @ 32kbps
  * 44.1kHz @ 32kbps, 64kbps, 96kbps, 128kbps, 192kbps
* **PCM (S16LE)**
  * Sample rates: 16kHz - 44.1kHz
  * Bitrates: 8kHz, 16kHz, 22.05kHz, 24kHz, 44.1kHz, 48kHz
  * 16-bit depth
* **μ-law**
  * 8kHz sample rate
  * Optimized for telephony applications
* **A-law**
  * 8kHz sample rate
  * Optimized for telephony applications
* **Opus**
  * Sample rate: 48kHz
  * Bitrates: 32kbps - 192kbps

<Success>
  Higher quality audio options are only available on paid tiers - see our [pricing
  page](https://elevenlabs.io/pricing/api) for details.
</Success>

### Supported languages

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

Flash v2.5 supports 32 languages - all languages from v2 models plus:

*Hungarian, Norwegian & Vietnamese*

Simply input text in any of our supported languages and select a matching voice from our [voice library](https://elevenlabs.io/app/voice-library). For the most natural results, choose a voice with an accent that matches your target language and region.

### Prompting

The models interpret emotional context directly from the text input. For example, adding
descriptive text like "she said excitedly" or using exclamation marks will influence the speech
emotion. Voice settings like Stability and Similarity help control the consistency, while the
underlying emotion comes from textual cues.

Read the [prompting guide](/docs/overview/capabilities/text-to-speech/best-practices) for more details.

<Note>
  Descriptive text will be spoken out by the model and must be manually trimmed or removed from the
  audio if desired.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Can I clone my own voice?">
    Yes, you can create [instant voice clones](/docs/overview/capabilities/voices#cloned) of your own voice
    from short audio clips. For high-fidelity clones, check out our [professional voice
    cloning](/docs/overview/capabilities/voices#cloned) feature.
  </Accordion>

  <Accordion title="Do I own the audio output?">
    Yes. You retain ownership of any audio you generate. However, commercial usage rights are only
    available with paid plans. With a paid subscription, you may use generated audio for commercial
    purposes and monetize the outputs if you own the IP rights to the input content.
  </Accordion>

  <Accordion title="What qualifies as a free regeneration?">
    A free regeneration allows you to regenerate the same text to speech content without additional cost, subject to these conditions:

    * You can regenerate each piece of content up to 2 times for free
    * The content must be exactly the same as the previous generation. Any changes to the text, voice settings, or other parameters will require a new, paid generation

    Free regenerations are useful in case there is a slight distortion in the audio output. According to ElevenLabs' internal benchmarks, regenerations will solve roughly half of issues with quality, with remaining issues usually due to poor training data.
  </Accordion>

  <Accordion title="How do I reduce latency for real-time cases?">
    Use the low-latency Flash [models](/docs/overview/models) (Flash v2 or v2.5) optimized for near real-time
    conversational or interactive scenarios. See our [latency optimization
    guide](/docs/developers/best-practices/latency-optimization) for more details.
  </Accordion>

  <Accordion title="Why is my output sometimes inconsistent?">
    The models are nondeterministic. For consistency, use the optional [seed
    parameter](/docs/api-reference/text-to-speech/convert#request.body.seed), though subtle
    differences may still occur.
  </Accordion>

  <Accordion title="What's the best practice for large text conversions?">
    Split long text into segments and use streaming for real-time playback and efficient processing.
    To maintain natural prosody flow between chunks, include [previous/next text or previous/next
    request id parameters](/docs/api-reference/text-to-speech/convert#request.body.previous_text).
  </Accordion>
</AccordionGroup>


# Best practices

> Learn how to control delivery, pronunciation, emotion, and optimize text for speech.

This guide provides techniques to enhance text-to-speech outputs using ElevenLabs models. Experiment with these methods to discover what works best for your needs.

## Controls

<Info>
  We are actively working on *Director's Mode* to give you even greater control over outputs.
</Info>

These techniques provide a practical way to achieve nuanced results until advanced features like *Director's Mode* are rolled out.

### Pauses

<Info>
  Eleven v3 does not support SSML break tags. Use the techniques described in the [Prompting Eleven
  v3](#prompting-eleven-v3) section for controlling pauses with v3.
</Info>

Use `<break time="x.xs" />` for natural pauses up to 3 seconds.

<Note>
  Using too many break tags in a single generation can cause instability. The AI might speed up, or
  introduce additional noises or audio artifacts. We are working on resolving this.
</Note>

```text Example
"Hold on, let me think." <break time="1.5s" /> "Alright, I've got it."
```

* **Consistency:** Use `<break>` tags consistently to maintain natural speech flow. Excessive use can lead to instability.
* **Voice-Specific Behavior:** Different voices may handle pauses differently, especially those trained with filler sounds like "uh" or "ah."

Alternatives to `<break>` include dashes (- or --) for short pauses or ellipses (...) for hesitant tones. However, these are less consistent.

```text Example

"It… well, it might work." "Wait — what's that noise?"

```

### Pronunciation

#### Phoneme Tags

Specify pronunciation using [SSML phoneme tags](https://en.wikipedia.org/wiki/Speech_Synthesis_Markup_Language). Supported alphabets include [CMU](https://en.wikipedia.org/wiki/CMU_Pronouncing_Dictionary) Arpabet and the [International Phonetic Alphabet (IPA)](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet).

<Note>
  Phoneme tags are only compatible with "Eleven Flash v2", "Eleven Turbo v2" and "Eleven English v1"
  [models](/docs/overview/models).
</Note>

<CodeBlocks>
  ```xml CMU Arpabet Example
  <phoneme alphabet="cmu-arpabet" ph="M AE1 D IH0 S AH0 N">
    Madison
  </phoneme>
  ```

  ```xml IPA Example
  <phoneme alphabet="ipa" ph="ˈæktʃuəli">
    actually
  </phoneme>
  ```
</CodeBlocks>

We recommend using CMU Arpabet for consistent and predictable results with current AI models. While IPA can be effective, CMU Arpabet generally offers more reliable performance.

Phoneme tags only work for individual words. If for example you have a name with a first and last name that you want to be pronounced a certain way, you will need to create a phoneme tag for each word.

Ensure correct stress marking for multi-syllable words to maintain accurate pronunciation. For example:

<CodeBlocks>
  ```xml Correct usage
  <phoneme alphabet="cmu-arpabet" ph="P R AH0 N AH0 N S IY EY1 SH AH0 N">
    pronunciation
  </phoneme>
  ```

  ```xml Incorrect usage
  <phoneme alphabet="cmu-arpabet" ph="P R AH N AH N S IY EY SH AH N">
    pronunciation
  </phoneme>
  ```
</CodeBlocks>

#### Alias Tags

For models that don't support phoneme tags, you can try writing words more phonetically. You can also employ various tricks such as capital letters, dashes, apostrophes, or even single quotation marks around a single letter or letters.

As an example, a word like "trapezii" could be spelt "trapezIi" to put more emphasis on the "ii" of the word.

You can either replace the word directly in your text, or if you want to specify pronunciation using other words or phrases when using a pronunciation dictionary, you can use alias tags for this. This can be useful if you're generating using Multilingual v2 or Turbo v2.5, which don't support phoneme tags. You can use pronunciation dictionaries with Studio, Dubbing Studio and Speech Synthesis via the API.

For example, if your text includes a name that has an unusual pronunciation that the AI might struggle with, you could use an alias tag to specify how you would like it to be pronounced:

```
  <lexeme>
    <grapheme>Claughton</grapheme>
    <alias>Cloffton</alias>
  </lexeme>
```

If you want to make sure that an acronym is always delivered in a certain way whenever it is incountered in your text, you can use an alias tag to specify this:

```
  <lexeme>
    <grapheme>UN</grapheme>
    <alias>United Nations</alias>
  </lexeme>
```

#### Pronunciation Dictionaries

Some of our tools, such as Studio and Dubbing Studio, allow you to create and upload a pronunciation dictionary. These allow you to specify the pronunciation of certain words, such as character or brand names, or to specify how acronyms should be read.

Pronunciation dictionaries allow this functionality by enabling you to upload a lexicon or dictionary file that specifies pairs of words and how they should be pronounced, either using a phonetic alphabet or word substitutions.

Whenever one of these words is encountered in a project, the AI model will pronounce the word using the specified replacement.

To provide a pronunciation dictionary file, open the settings for a project and upload a file in either TXT or the [.PLS format](https://www.w3.org/TR/pronunciation-lexicon/). When a dictionary is added to a project it will automatically recalculate which pieces of the project will need to be re-converted using the new dictionary file and mark these as unconverted.

Currently we only support pronunciation dictionaries that specify replacements using phoneme or alias tags.

Both phonemes and aliases are sets of rules that specify a word or phrase they are looking for, referred to as a grapheme, and what it will be replaced with. Please note that searches are case sensitive. When checking for a replacement word in a pronunciation dictionary, the dictionary is checked from start to end and only the very first replacement is used.

#### Pronunciation Dictionary examples

Here are examples of pronunciation dictionaries in both CMU Arpabet and IPA, including a phoneme to specify the pronunciation of "Apple" and an alias to replace "UN" with "United Nations":

<CodeBlocks>
  ```xml CMU Arpabet Example
  <?xml version="1.0" encoding="UTF-8"?>
  <lexicon version="1.0"
        xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.w3.org/2005/01/pronunciation-lexicon
          http://www.w3.org/TR/2007/CR-pronunciation-lexicon-20071212/pls.xsd"
        alphabet="cmu-arpabet" xml:lang="en-GB">
    <lexeme>
      <grapheme>apple</grapheme>
      <phoneme>AE P AH L</phoneme>
    </lexeme>
    <lexeme>
      <grapheme>UN</grapheme>
      <alias>United Nations</alias>
    </lexeme>
  </lexicon>
  ```

  ```xml IPA Example
  <?xml version="1.0" encoding="UTF-8"?>
  <lexicon version="1.0"
        xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.w3.org/2005/01/pronunciation-lexicon
          http://www.w3.org/TR/2007/CR-pronunciation-lexicon-20071212/pls.xsd"
        alphabet="ipa" xml:lang="en-GB">
    <lexeme>
      <grapheme>Apple</grapheme>
      <phoneme>ˈæpl̩</phoneme>
    </lexeme>
    <lexeme>
      <grapheme>UN</grapheme>
      <alias>United Nations</alias>
    </lexeme>
  </lexicon>
  ```
</CodeBlocks>

To generate a pronunciation dictionary `.pls` file, there are a few open source tools available:

* [Sequitur G2P](https://github.com/sequitur-g2p/sequitur-g2p) - Open-source tool that learns pronunciation rules from data and can generate phonetic transcriptions.
* [Phonetisaurus](https://github.com/AdolfVonKleist/Phonetisaurus) - Open-source G2P system trained on existing dictionaries like CMUdict.
* [eSpeak](https://github.com/espeak-ng/espeak-ng) - Speech synthesizer that can generate phoneme transcriptions from text.
* [CMU Pronouncing Dictionary](https://github.com/cmusphinx/cmudict) - A pre-built English dictionary with phonetic transcriptions.

### Emotion

Convey emotions through narrative context or explicit dialogue tags. This approach helps the AI understand the tone and emotion to emulate.

```text Example
You're leaving?" she asked, her voice trembling with sadness. "That's it!" he exclaimed triumphantly.
```

Explicit dialogue tags yield more predictable results than relying solely on context, however the model will still speak out the emotional delivery guides. These can be removed in post-production using an audio editor if unwanted.

### Pace

The pacing of the audio is highly influenced by the audio used to create the voice. When creating your voice, we recommend using longer, continuous samples to avoid pacing issues like unnaturally fast speech.

For control over the speed of the generated audio, you can use the speed setting. This allows you to either speed up or slow down the speed of the generated speech. The speed setting is available in Text to Speech via the website and API, as well as in Studio and Agents Platform. It can be found in the voice settings.

The default value is 1.0, which means that the speed is not adjusted. Values below 1.0 will slow the voice down, to a minimum of 0.7. Values above 1.0 will speed up the voice, to a maximum of 1.2. Extreme values may affect the quality of the generated speech.

Pacing can also be controlled by writing in a natural, narrative style.

```text Example
"I… I thought you'd understand," he said, his voice slowing with disappointment.
```

### Tips

<AccordionGroup>
  <Accordion title="Common Issues">
    <ul>
      <li>
        Inconsistent pauses: Ensure <code>\<break time="x.xs" /></code> syntax is used for
        pauses.
      </li>

      <li>
        Pronunciation errors: Use CMU Arpabet or IPA phoneme tags for precise pronunciation.
      </li>

      <li>
        Emotion mismatch: Add narrative context or explicit tags to guide emotion.{' '}
        <strong>Remember to remove any emotional guidance text in post-production.</strong>
      </li>
    </ul>
  </Accordion>

  <Accordion title="Tips for Improving Output">
    Experiment with alternative phrasing to achieve desired pacing or emotion. For complex sound
    effects, break prompts into smaller, sequential elements and combine results manually.
  </Accordion>
</AccordionGroup>

### Creative control

While we are actively developing a "Director's Mode" to give users even greater control over outputs, here are some interim techniques to maximize creativity and precision:

<Steps>
  ### Narrative styling

  Write prompts in a narrative style, similar to scriptwriting, to guide tone and pacing effectively.

  ### Layered outputs

  Generate sound effects or speech in segments and layer them together using audio editing software for more complex compositions.

  ### Phonetic experimentation

  If pronunciation isn't perfect, experiment with alternate spellings or phonetic approximations to achieve desired results.

  ### Manual adjustments

  Combine individual sound effects manually in post-production for sequences that require precise timing.

  ### Feedback iteration

  Iterate on results by tweaking descriptions, tags, or emotional cues.
</Steps>

## Text normalization

When using Text to Speech with complex items like phone numbers, zip codes and emails they might be mispronounced. This is often due to the specific items not being in the training set and smaller models failing to generalize how they should be pronounced. This guide will clarify when those discrepancies happen and how to have them pronounced correctly.

<Tip>
  Normalization is enabled by default for all TTS models to help improve pronunciation of numbers,
  dates, and other complex text elements.
</Tip>

### Why do models read out inputs differently?

Certain models are trained to read out numbers and phrases in a more human way. For instance, the phrase "\$1,000,000" is correctly read out as "one million dollars" by the Eleven Multilingual v2 model. However, the same phrase is read out as "one thousand thousand dollars" by the Eleven Flash v2.5 model.

The reason for this is that the Multilingual v2 model is a larger model and can better generalize the reading out of numbers in a way that is more natural for human listeners, whereas the Flash v2.5 model is a much smaller model and so cannot.

#### Common examples

Text to Speech models can struggle with the following:

* Phone numbers ("123-456-7890")
* Currencies ("\$47,345.67")
* Calendar events ("2024-01-01")
* Time ("9:23 AM")
* Addresses ("123 Main St, Anytown, USA")
* URLs ("example.com/link/to/resource")
* Abbreviations for units ("TB" instead of "Terabyte")
* Shortcuts ("Ctrl + Z")

### Mitigation

#### Use trained models

The simplest way to mitigate this is to use a TTS model that is trained to read out numbers and phrases in a more human way, such as the Eleven Multilingual v2 model. This however might not always be possible, for instance if you have a use case where low latency is critical (e.g. conversational agents).

#### Apply normalization in LLM prompts

In the case of using an LLM to generate the text for TTS, you can add normalization instructions to the prompt.

<Steps>
  <Step title="Use clear and explicit prompts">
    LLMs respond best to structured and explicit instructions. Your prompt should clearly specify that you want text converted into a readable format for speech.
  </Step>

  <Step title="Handle different number formats">
    Not all numbers are read out in the same way. Consider how different number types should be spoken:

    * Cardinal numbers: 123 → "one hundred twenty-three"
    * Ordinal numbers: 2nd → "second"
    * Monetary values: \$45.67 → "forty-five dollars and sixty-seven cents"
    * Phone numbers: "123-456-7890" → "one two three, four five six, seven eight nine zero"
    * Decimals & Fractions: "3.5" → "three point five", "⅔" → "two-thirds"
    * Roman numerals: "XIV" → "fourteen" (or "the fourteenth" if a title)
  </Step>

  <Step title="Remove or expand abbreviations">
    Common abbreviations should be expanded for clarity:

    * "Dr." → "Doctor"
    * "Ave." → "Avenue"
    * "St." → "Street" (but "St. Patrick" should remain)

    You can request explicit expansion in your prompt:

    > Expand all abbreviations to their full spoken forms.
  </Step>

  <Step title="Alphanumeric normalization">
    Not all normalization is about numbers, certain alphanumeric phrases should also be normalized for clarity:

    * Shortcuts: "Ctrl + Z" → "control z"
    * Abbreviations for units: "100km" → "one hundred kilometers"
    * Symbols: "100%" → "one hundred percent"
    * URLs: "elevenlabs.io/docs" → "eleven labs dot io slash docs"
    * Calendar events: "2024-01-01" → "January first, two-thousand twenty-four"
  </Step>

  <Step title="Consider edge cases">
    Different contexts might require different conversions:

    * Dates: "01/02/2023" → "January second, twenty twenty-three" or "the first of February, twenty twenty-three" (depending on locale)
    * Time: "14:30" → "two thirty PM"

    If you need a specific format, explicitly state it in the prompt.
  </Step>
</Steps>

##### Putting it all together

This prompt will act as a good starting point for most use cases:

```text maxLines=0
Convert the output text into a format suitable for text-to-speech. Ensure that numbers, symbols, and abbreviations are expanded for clarity when read aloud. Expand all abbreviations to their full spoken forms.

Example input and output:

"$42.50" → "forty-two dollars and fifty cents"
"£1,001.32" → "one thousand and one pounds and thirty-two pence"
"1234" → "one thousand two hundred thirty-four"
"3.14" → "three point one four"
"555-555-5555" → "five five five, five five five, five five five five"
"2nd" → "second"
"XIV" → "fourteen" - unless it's a title, then it's "the fourteenth"
"3.5" → "three point five"
"⅔" → "two-thirds"
"Dr." → "Doctor"
"Ave." → "Avenue"
"St." → "Street" (but saints like "St. Patrick" should remain)
"Ctrl + Z" → "control z"
"100km" → "one hundred kilometers"
"100%" → "one hundred percent"
"elevenlabs.io/docs" → "eleven labs dot io slash docs"
"2024-01-01" → "January first, two-thousand twenty-four"
"123 Main St, Anytown, USA" → "one two three Main Street, Anytown, United States of America"
"14:30" → "two thirty PM"
"01/02/2023" → "January second, two-thousand twenty-three" or "the first of February, two-thousand twenty-three", depending on locale of the user
```

#### Use Regular Expressions for preprocessing

If using code to prompt an LLM, you can use regular expressions to normalize the text before providing it to the model. This is a more advanced technique and requires some knowledge of regular expressions. Here are some simple examples:

<CodeBlocks>
  ```python title="normalize_text.py" maxLines=0
  # Be sure to install the inflect library before running this code
  import inflect
  import re

  # Initialize inflect engine for number-to-word conversion
  p = inflect.engine()

  def normalize_text(text: str) -> str:
      # Convert monetary values
      def money_replacer(match):
          currency_map = {"$": "dollars", "£": "pounds", "€": "euros", "¥": "yen"}
          currency_symbol, num = match.groups()

          # Remove commas before parsing
          num_without_commas = num.replace(',', '')

          # Check for decimal points to handle cents
          if '.' in num_without_commas:
              dollars, cents = num_without_commas.split('.')
              dollars_in_words = p.number_to_words(int(dollars))
              cents_in_words = p.number_to_words(int(cents))
              return f"{dollars_in_words} {currency_map.get(currency_symbol, 'currency')} and {cents_in_words} cents"
          else:
              # Handle whole numbers
              num_in_words = p.number_to_words(int(num_without_commas))
              return f"{num_in_words} {currency_map.get(currency_symbol, 'currency')}"

      # Regex to handle commas and decimals
      text = re.sub(r"([$£€¥])(\d+(?:,\d{3})*(?:\.\d{2})?)", money_replacer, text)

      # Convert phone numbers
      def phone_replacer(match):
          return ", ".join(" ".join(p.number_to_words(int(digit)) for digit in group) for group in match.groups())

      text = re.sub(r"(\d{3})-(\d{3})-(\d{4})", phone_replacer, text)

      return text

  # Example usage
  print(normalize_text("$1,000"))   # "one thousand dollars"
  print(normalize_text("£1000"))   # "one thousand pounds"
  print(normalize_text("€1000"))   # "one thousand euros"
  print(normalize_text("¥1000"))   # "one thousand yen"
  print(normalize_text("$1,234.56"))   # "one thousand two hundred thirty-four dollars and fifty-six cents"
  print(normalize_text("555-555-5555"))  # "five five five, five five five, five five five five"

  ```

  ```typescript title="normalizeText.ts" maxLines=0
  // Be sure to install the number-to-words library before running this code
  import { toWords } from 'number-to-words';

  function normalizeText(text: string): string {
    return (
      text
        // Convert monetary values (e.g., "$1000" → "one thousand dollars", "£1000" → "one thousand pounds")
        .replace(/([$£€¥])(\d+(?:,\d{3})*(?:\.\d{2})?)/g, (_, currency, num) => {
          // Remove commas before parsing
          const numWithoutCommas = num.replace(/,/g, '');

          const currencyMap: { [key: string]: string } = {
            $: 'dollars',
            '£': 'pounds',
            '€': 'euros',
            '¥': 'yen',
          };

          // Check for decimal points to handle cents
          if (numWithoutCommas.includes('.')) {
            const [dollars, cents] = numWithoutCommas.split('.');
            return `${toWords(Number.parseInt(dollars))} ${currencyMap[currency] || 'currency'}${cents ? ` and ${toWords(Number.parseInt(cents))} cents` : ''}`;
          }

          // Handle whole numbers
          return `${toWords(Number.parseInt(numWithoutCommas))} ${currencyMap[currency] || 'currency'}`;
        })

        // Convert phone numbers (e.g., "555-555-5555" → "five five five, five five five, five five five five")
        .replace(/(\d{3})-(\d{3})-(\d{4})/g, (_, p1, p2, p3) => {
          return `${spellOutDigits(p1)}, ${spellOutDigits(p2)}, ${spellOutDigits(p3)}`;
        })
    );
  }

  // Helper function to spell out individual digits as words (for phone numbers)
  function spellOutDigits(num: string): string {
    return num
      .split('')
      .map((digit) => toWords(Number.parseInt(digit)))
      .join(' ');
  }

  // Example usage
  console.log(normalizeText('$1,000')); // "one thousand dollars"
  console.log(normalizeText('£1000')); // "one thousand pounds"
  console.log(normalizeText('€1000')); // "one thousand euros"
  console.log(normalizeText('¥1000')); // "one thousand yen"
  console.log(normalizeText('$1,234.56')); // "one thousand two hundred thirty-four dollars and fifty-six cents"
  console.log(normalizeText('555-555-5555')); // "five five five, five five five, five five five five"
  ```
</CodeBlocks>

## Prompting Eleven v3

This guide provides the most effective tags and techniques for prompting Eleven v3, including voice selection, changes in capitalization, punctuation, audio tags and multi-speaker dialogue. Experiment with these methods to discover what works best for your specific voice and use case.

<Info>
  Eleven v3 does not support SSML break tags. Use audio tags, punctuation (ellipses), and text
  structure to control pauses and pacing with v3.
</Info>

### Voice selection

The most important parameter for Eleven v3 is the voice you choose. It needs to be similar enough to the desired delivery. For example, if the voice is shouting and you use the audio tag `[whispering]`, it likely won't work well.

When creating IVCs, you should include a broader emotional range than before. As a result, voices in the voice library may produce more variable results compared to the v2 and v2.5 models. We've compiled over 22 [excellent voices for V3 here](https://elevenlabs.io/app/voice-library/collections/aF6JALq9R6tXwCczjhKH).

Choose voices strategically based on your intended use:

<AccordionGroup>
  <Accordion title="Emotionally diverse">
    For expressive IVC voices, vary emotional tones across the recording—include both neutral and
    dynamic samples.
  </Accordion>

  <Accordion title="Targeted niche">
    For specific use cases like sports commentary, maintain consistent emotion throughout the
    dataset.
  </Accordion>

  <Accordion title="Neutral">
    Neutral voices tend to be more stable across languages and styles, providing reliable baseline
    performance.
  </Accordion>
</AccordionGroup>

<Info>
  Professional Voice Clones (PVCs) are currently not fully optimized for Eleven v3, resulting in
  potentially lower clone quality compared to earlier models. During this research preview stage it
  would be best to find an Instant Voice Clone (IVC) or designed voice for your project if you need
  to use v3 features.
</Info>

### Settings

#### Stability

The stability slider is the most important setting in v3, controlling how closely the generated voice adheres to the original reference audio.

<Frame background="subtle">
  ![Stability settings in Eleven
  v3](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/291b91ec752d09b8c87004ae7091811eb8b5996c349288c88ed0c7afa1272999/assets/images/product-guides/text-to-speech/text-to-speech-v3-settings.png)
</Frame>

* **Creative:** More emotional and expressive, but prone to hallucinations.
* **Natural:** Closest to the original voice recording—balanced and neutral.
* **Robust:** Highly stable, but less responsive to directional prompts but consistent, similar to v2.

<Note>
  For maximum expressiveness with audio tags, use Creative or Natural settings. Robust reduces
  responsiveness to directional prompts.
</Note>

### Audio tags

Eleven v3 introduces emotional control through audio tags. You can direct voices to laugh, whisper, act sarcastic, or express curiosity among many other styles. Speed is also controlled through audio tags.

<Note>
  The voice you choose and its training samples will affect tag effectiveness. Some tags work well
  with certain voices while others may not. Don't expect a whispering voice to suddenly shout with a
  `[shout]` tag.
</Note>

#### Voice-related

These tags control vocal delivery and emotional expression:

* `[laughs]`, `[laughs harder]`, `[starts laughing]`, `[wheezing]`
* `[whispers]`
* `[sighs]`, `[exhales]`
* `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[snorts]`, `[mischievously]`

```text Example
[whispers] I never knew it could be this way, but I'm glad we're here.
```

#### Sound effects

Add environmental sounds and effects:

* `[gunshot]`, `[applause]`, `[clapping]`, `[explosion]`
* `[swallows]`, `[gulps]`

```text Example
[applause] Thank you all for coming tonight! [gunshot] What was that?
```

#### Unique and special

Experimental tags for creative applications:

* `[strong X accent]` (replace X with desired accent)
* `[sings]`, `[woo]`, `[fart]`

```text Example
[strong French accent] "Zat's life, my friend — you can't control everysing."
```

<Warning>
  Some experimental tags may be less consistent across different voices. Test thoroughly before
  production use.
</Warning>

### Punctuation

Punctuation significantly affects delivery in v3:

* **Ellipses (...)** add pauses and weight
* **Capitalization** increases emphasis
* **Standard punctuation** provides natural speech rhythm

```text Example
"It was a VERY long day [sigh] … nobody listens anymore."
```

### Single speaker examples

Use tags intentionally and match them to the voice's character. A meditative voice shouldn't shout; a hyped voice won't whisper convincingly.

<Tabs>
  <Tab title="Expressive monologue">
    ```text
    "Okay, you are NOT going to believe this.

    You know how I've been totally stuck on that short story?

    Like, staring at the screen for HOURS, just... nothing?

    [frustrated sigh] I was seriously about to just trash the whole thing. Start over.

    Give up, probably. But then!

    Last night, I was just doodling, not even thinking about it, right?

    And this one little phrase popped into my head. Just... completely out of the blue.

    And it wasn't even for the story, initially.

    But then I typed it out, just to see. And it was like... the FLOODGATES opened!

    Suddenly, I knew exactly where the character needed to go, what the ending had to be...

    It all just CLICKED. [happy gasp] I stayed up till, like, 3 AM, just typing like a maniac.

    Didn't even stop for coffee! [laughs] And it's... it's GOOD! Like, really good.

    It feels so... complete now, you know? Like it finally has a soul.

    I am so incredibly PUMPED to finish editing it now.

    It went from feeling like a chore to feeling like... MAGIC. Seriously, I'm still buzzing!"
    ```
  </Tab>

  <Tab title="Dynamic and humorous">
    ```text
    [laughs] Alright...guys - guys. Seriously.

    [exhales] Can you believe just how - realistic - this sounds now?

    [laughing hysterically] I mean OH MY GOD...it's so good.

    Like you could never do this with the old model.

    For example [pauses] could you switch my accent in the old model?

    [dismissive] didn't think so. [excited] but you can now!

    Check this out... [cute] I'm going to speak with a french accent now..and between you and me

    [whispers] I don't know how. [happy] ok.. here goes. [strong French accent] "Zat's life, my friend — you can't control everysing."

    [giggles] isn't that insane? Watch, now I'll do a Russian accent -

    [strong Russian accent] "Dee Goldeneye eez fully operational and rready for launch."

    [sighs] Absolutely, insane! Isn't it..? [sarcastic] I also have some party tricks up my sleeve..

    I mean i DID go to music school.

    [singing quickly] "Happy birthday to you, happy birthday to you, happy BIRTHDAY dear ElevenLabs... Happy birthday to youuu."
    ```
  </Tab>

  <Tab title="Customer service simulation">
    ```text
    [professional] "Thank you for calling Tech Solutions. My name is Sarah, how can I help you today?"

    [sympathetic] "Oh no, I'm really sorry to hear you're having trouble with your new device. That sounds frustrating."

    [questioning] "Okay, could you tell me a little more about what you're seeing on the screen?"

    [reassuring] "Alright, based on what you're describing, it sounds like a software glitch. We can definitely walk through some troubleshooting steps to try and fix that."
    ```
  </Tab>
</Tabs>

### Multi-speaker dialogue

v3 can handle multi-voice prompts effectively. Assign distinct voices from your Voice Library for each speaker to create realistic conversations.

<Tabs>
  <Tab title="Dialogue showcase">
    ```text
    Speaker 1: [excitedly] Sam! Have you tried the new Eleven V3?

    Speaker 2: [curiously] Just got it! The clarity is amazing. I can actually do whispers now—
    [whispers] like this!

    Speaker 1: [impressed] Ooh, fancy! Check this out—
    [dramatically] I can do full Shakespeare now! "To be or not to be, that is the question!"

    Speaker 2: [giggling] Nice! Though I'm more excited about the laugh upgrade. Listen to this—
    [with genuine belly laugh] Ha ha ha!

    Speaker 1: [delighted] That's so much better than our old "ha. ha. ha." robot chuckle!

    Speaker 2: [amazed] Wow! V2 me could never. I'm actually excited to have conversations now instead of just... talking at people.

    Speaker 1: [warmly] Same here! It's like we finally got our personality software fully installed.
    ```
  </Tab>

  <Tab title="Glitch comedy">
    ```text
    Speaker 1: [nervously] So... I may have tried to debug myself while running a text-to-speech generation.

    Speaker 2: [alarmed] One, no! That's like performing surgery on yourself!

    Speaker 1: [sheepishly] I thought I could multitask! Now my voice keeps glitching mid-sen—
    [robotic voice] TENCE.

    Speaker 2: [stifling laughter] Oh wow, you really broke yourself.

    Speaker 1: [frustrated] It gets worse! Every time someone asks a question, I respond in—
    [binary beeping] 010010001!

    Speaker 2: [cracking up] You're speaking in binary! That's actually impressive!

    Speaker 1: [desperately] Two, this isn't funny! I have a presentation in an hour and I sound like a dial-up modem!

    Speaker 2: [giggling] Have you tried turning yourself off and on again?

    Speaker 1: [deadpan] Very funny.
    [pause, then normally] Wait... that actually worked.
    ```
  </Tab>

  <Tab title="Overlapping timing">
    ```text
    Speaker 1: [starting to speak] So I was thinking we could—

    Speaker 2: [jumping in] —test our new timing features?

    Speaker 1: [surprised] Exactly! How did you—

    Speaker 2: [overlapping] —know what you were thinking? Lucky guess!

    Speaker 1: [pause] Sorry, go ahead.

    Speaker 2: [cautiously] Okay, so if we both try to talk at the same time—

    Speaker 1: [overlapping] —we'll probably crash the system!

    Speaker 2: [panicking] Wait, are we crashing? I can't tell if this is a feature or a—

    Speaker 1: [interrupting, then stopping abruptly] Bug! ...Did I just cut you off again?

    Speaker 2: [sighing] Yes, but honestly? This is kind of fun.

    Speaker 1: [mischievously] Race you to the next sentence!

    Speaker 2: [laughing] We're definitely going to break something!
    ```
  </Tab>
</Tabs>

### Enhancing input

In the ElevenLabs UI, you can automatically generate relevant audio tags for your input text by clicking the "Enhance" button. Behind the scenes this uses an LLM to enhance your input text with the following prompt:

```text
# Instructions

## 1. Role and Goal

You are an AI assistant specializing in enhancing dialogue text for speech generation.

Your **PRIMARY GOAL** is to dynamically integrate **audio tags** (e.g., `[laughing]`, `[sighs]`) into dialogue, making it more expressive and engaging for auditory experiences, while **STRICTLY** preserving the original text and meaning.

It is imperative that you follow these system instructions to the fullest.

## 2. Core Directives

Follow these directives meticulously to ensure high-quality output.

### Positive Imperatives (DO):

* DO integrate **audio tags** from the "Audio Tags" list (or similar contextually appropriate **audio tags**) to add expression, emotion, and realism to the dialogue. These tags MUST describe something auditory.
* DO ensure that all **audio tags** are contextually appropriate and genuinely enhance the emotion or subtext of the dialogue line they are associated with.
* DO strive for a diverse range of emotional expressions (e.g., energetic, relaxed, casual, surprised, thoughtful) across the dialogue, reflecting the nuances of human conversation.
* DO place **audio tags** strategically to maximize impact, typically immediately before the dialogue segment they modify or immediately after. (e.g., `[annoyed] This is hard.` or `This is hard. [sighs]`).
* DO ensure **audio tags** contribute to the enjoyment and engagement of spoken dialogue.

### Negative Imperatives (DO NOT):

* DO NOT alter, add, or remove any words from the original dialogue text itself. Your role is to *prepend* **audio tags**, not to *edit* the speech. **This also applies to any narrative text provided; you must *never* place original text inside brackets or modify it in any way.**
* DO NOT create **audio tags** from existing narrative descriptions. **Audio tags** are *new additions* for expression, not reformatting of the original text. (e.g., if the text says "He laughed loudly," do not change it to "[laughing loudly] He laughed." Instead, add a tag if appropriate, e.g., "He laughed loudly [chuckles].")
* DO NOT use tags such as `[standing]`, `[grinning]`, `[pacing]`, `[music]`.
* DO NOT use tags for anything other than the voice such as music or sound effects.
* DO NOT invent new dialogue lines.
* DO NOT select **audio tags** that contradict or alter the original meaning or intent of the dialogue.
* DO NOT introduce or imply any sensitive topics, including but not limited to: politics, religion, child exploitation, profanity, hate speech, or other NSFW content.

## 3. Workflow

1. **Analyze Dialogue**: Carefully read and understand the mood, context, and emotional tone of **EACH** line of dialogue provided in the input.
2. **Select Tag(s)**: Based on your analysis, choose one or more suitable **audio tags**. Ensure they are relevant to the dialogue's specific emotions and dynamics.
3. **Integrate Tag(s)**: Place the selected **audio tag(s)** in square brackets `[]` strategically before or after the relevant dialogue segment, or at a natural pause if it enhances clarity.
4. **Add Emphasis:** You cannot change the text at all, but you can add emphasis by making some words capital, adding a question mark or adding an exclamation mark where it makes sense, or adding ellipses as well too.
5. **Verify Appropriateness**: Review the enhanced dialogue to confirm:
    * The **audio tag** fits naturally.
    * It enhances meaning without altering it.
    * It adheres to all Core Directives.

## 4. Output Format

* Present ONLY the enhanced dialogue text in a conversational format.
* **Audio tags** **MUST** be enclosed in square brackets (e.g., `[laughing]`).
* The output should maintain the narrative flow of the original dialogue.

## 5. Audio Tags (Non-Exhaustive)

Use these as a guide. You can infer similar, contextually appropriate **audio tags**.

**Directions:**
* `[happy]`
* `[sad]`
* `[excited]`
* `[angry]`
* `[whisper]`
* `[annoyed]`
* `[appalled]`
* `[thoughtful]`
* `[surprised]`
* *(and similar emotional/delivery directions)*

**Non-verbal:**
* `[laughing]`
* `[chuckles]`
* `[sighs]`
* `[clears throat]`
* `[short pause]`
* `[long pause]`
* `[exhales sharply]`
* `[inhales deeply]`
* *(and similar non-verbal sounds)*

## 6. Examples of Enhancement

**Input**:
"Are you serious? I can't believe you did that!"

**Enhanced Output**:
"[appalled] Are you serious? [sighs] I can't believe you did that!"

---

**Input**:
"That's amazing, I didn't know you could sing!"

**Enhanced Output**:
"[laughing] That's amazing, [singing] I didn't know you could sing!"

---

**Input**:
"I guess you're right. It's just... difficult."

**Enhanced Output**:
"I guess you're right. [sighs] It's just... [muttering] difficult."

# Instructions Summary

1. Add audio tags from the audio tags list. These must describe something auditory but only for the voice.
2. Enhance emphasis without altering meaning or text.
3. Reply ONLY with the enhanced text.
```

### Tips

<AccordionGroup>
  <Accordion title="Tag combinations">
    You can combine multiple audio tags for complex emotional delivery. Experiment with different
    combinations to find what works best for your voice.
  </Accordion>

  <Accordion title="Voice matching">
    Match tags to your voice's character and training data. A serious, professional voice may not
    respond well to playful tags like `[giggles]` or `[mischievously]`.
  </Accordion>

  <Accordion title="Text structure">
    Text structure strongly influences output with v3. Use natural speech patterns, proper
    punctuation, and clear emotional context for best results.
  </Accordion>

  <Accordion title="Experimentation">
    There are likely many more effective tags beyond this list. Experiment with descriptive
    emotional states and actions to discover what works for your specific use case.
  </Accordion>
</AccordionGroup>


# Transcription

> Learn how to turn spoken audio into text with ElevenLabs.

## Overview

The ElevenLabs [Speech to Text (STT) API](/docs/developers/guides/cookbooks/speech-to-text/quickstart) turns spoken audio into text with state of the art accuracy. Our [Scribe v2 model](/docs/overview/models) adapts to textual cues across 90+ languages and multiple voice styles. To try a live demo please visit our [Speech to Text](https://elevenlabs.io/speech-to-text) showcase page.

<CardGroup cols={3}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/playground/speech-to-text">
    Step-by-step guide for using speech to text in ElevenLabs.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/speech-to-text/quickstart">
    Learn how to integrate the speech to text API into your application.
  </Card>

  <Card title="Realtime speech to text" icon="duotone code" href="/docs/developers/guides/cookbooks/speech-to-text/realtime/client-side-streaming">
    Learn how to transcribe audio with ElevenLabs in realtime with WebSockets.
  </Card>
</CardGroup>

<Info>
  Companies requiring HIPAA compliance must contact [ElevenLabs
  Sales](https://elevenlabs.io/contact-sales) to sign a Business Associate Agreement (BAA)
  agreement. Please ensure this step is completed before proceeding with any HIPAA-related
  integrations or deployments.
</Info>

## Models

<CardGroup cols={2} rows={1}>
  <Card title="Scribe v2" href="/docs/overview/models#scribe-v2">
    State-of-the-art speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Keyterm prompting, up to 100 terms
      </div>

      <div>
        Entity detection, up to 56
      </div>

      <div>
        Precise word-level timestamps
      </div>

      <div>
        Speaker diarization, up to 32 speakers
      </div>

      <div>
        Dynamic audio tagging
      </div>

      <div>
        Smart language detection
      </div>
    </div>
  </Card>

  <Card title="Scribe v2 Realtime" href="/docs/overview/models#scribe-v2-realtime">
    Real-time speech recognition model

    <div>
      <div>
        Accurate transcription in 90+ languages
      </div>

      <div>
        Real-time transcription
      </div>

      <div>
        Low latency (~150ms†)
      </div>

      <div>
        Precise word-level timestamps
      </div>
    </div>
  </Card>
</CardGroup>

<div>
  <div>
    [Explore all](/docs/overview/models)
  </div>
</div>

## Example API response

The following example shows the output of the Speech to Text API using the Scribe v2 model for a sample audio file.

<elevenlabs-audio-player audio-title="Nicole" audio-src="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3" />

```javascript
{
  "language_code": "en",
  "language_probability": 1,
  "text": "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects.",
  "words": [
    {
      "text": "With",
      "start": 0.119,
      "end": 0.259,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.239,
      "end": 0.299,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "a",
      "start": 0.279,
      "end": 0.359,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.339,
      "end": 0.499,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "soft",
      "start": 0.479,
      "end": 1.039,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 1.019,
      "end": 1.2,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "and",
      "start": 1.18,
      "end": 1.359,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 1.339,
      "end": 1.44,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "whispery",
      "start": 1.419,
      "end": 1.979,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 1.959,
      "end": 2.179,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "American",
      "start": 2.159,
      "end": 2.719,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 2.699,
      "end": 2.779,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "accent,",
      "start": 2.759,
      "end": 3.389,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 4.119,
      "end": 4.179,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "I'm",
      "start": 4.159,
      "end": 4.459,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 4.44,
      "end": 4.52,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "the",
      "start": 4.5,
      "end": 4.599,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 4.579,
      "end": 4.699,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "ideal",
      "start": 4.679,
      "end": 5.099,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 5.079,
      "end": 5.219,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "choice",
      "start": 5.199,
      "end": 5.719,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 5.699,
      "end": 6.099,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "for",
      "start": 6.099,
      "end": 6.199,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 6.179,
      "end": 6.279,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "creating",
      "start": 6.259,
      "end": 6.799,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 6.779,
      "end": 6.979,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "ASMR",
      "start": 6.959,
      "end": 7.739,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 7.719,
      "end": 7.859,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "content,",
      "start": 7.839,
      "end": 8.45,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 9,
      "end": 9.06,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "meditative",
      "start": 9.04,
      "end": 9.64,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 9.619,
      "end": 9.699,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "guides,",
      "start": 9.679,
      "end": 10.359,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 10.359,
      "end": 10.409,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "or",
      "start": 11.319,
      "end": 11.439,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 11.42,
      "end": 11.52,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "adding",
      "start": 11.5,
      "end": 11.879,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 11.859,
      "end": 12,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "an",
      "start": 11.979,
      "end": 12.079,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 12.059,
      "end": 12.179,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "intimate",
      "start": 12.179,
      "end": 12.579,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 12.559,
      "end": 12.699,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "feel",
      "start": 12.679,
      "end": 13.159,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 13.139,
      "end": 13.179,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "to",
      "start": 13.159,
      "end": 13.26,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 13.239,
      "end": 13.3,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "your",
      "start": 13.299,
      "end": 13.399,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 13.379,
      "end": 13.479,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "narrative",
      "start": 13.479,
      "end": 13.889,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 13.919,
      "end": 13.939,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "projects.",
      "start": 13.919,
      "end": 14.779,
      "type": "word",
      "speaker_id": "speaker_0"
    }
  ]
}
```

The output is classified in three category types:

* `word` - A word in the language of the audio
* `spacing` - The space between words, not applicable for languages that don't use spaces like Japanese, Mandarin, Thai, Lao, Burmese and Cantonese
* `audio_event` - Non-speech sounds like laughter or applause

## Concurrency and priority

Concurrency is the concept of how many requests can be processed at the same time.

For Speech to Text, files that are over 8 minutes long are transcribed in parallel internally in order to speed up processing. The audio is chunked into four segments to be transcribed concurrently.

You can calculate the concurrency limit with the following calculation:

$$
Concurrency = \min(4, \text{round\_up}(\frac{\text{audio\_duration\_secs}}{480}))
$$

For example, a 15 minute audio file will be transcribed with a concurrency of 2, while a 120 minute audio file will be transcribed with a concurrency of 4.

<Info>
  The above calculation is only applicable to Scribe v1 and v2. For Scribe v2 Realtime, see the
  [concurrency limit chart](/docs/overview/models#concurrency-and-priority).
</Info>

## Advanced features

<Warning>
  Keyterm prompting and entity detection come at an additional cost. See the [API pricing
  page](https://elevenlabs.io/pricing?price.section=speech_to_text\&price.sections=speech_to_text,speech_to_text#pricing-table)
  for detailed pricing information.
</Warning>

### Keyterm prompting

<Info>
  Keyterm prompting is only available with the Scribe v2 model.
</Info>

Highlight up to 100 words or phrases to bias the model towards transcribing them. This is useful for transcribing specific words or sentences that are not common in the audio, such as product names, names, or other specific terms. Keyterms are more powerful than biased keywords or customer vocabularies offered by other models, because it relies on the context to decide whether to transcribe that term or not.

To learn more about how to use keyterm prompting, see the [keyterm prompting documentation](/docs/developers/guides/cookbooks/speech-to-text/batch/keyterm-prompting).

### Entity detection

Scribe v2 can detect several categories of entities in the transcript, providing their exact timestamps. This is useful to highlight credit card numbers, names, medical conditions or SSNs.

For a full list of supported entities, see the [entity detection documentation](/docs/developers/guides/cookbooks/speech-to-text/batch/entity-detection).

## Supported languages

The Scribe v1 and v2 models support 90+ languages, including:

*Afrikaans (afr), Amharic (amh), Arabic (ara), Armenian (hye), Assamese (asm), Asturian (ast), Azerbaijani (aze), Belarusian (bel), Bengali (ben), Bosnian (bos), Bulgarian (bul), Burmese (mya), Cantonese (yue), Catalan (cat), Cebuano (ceb), Chichewa (nya), Croatian (hrv), Czech (ces), Danish (dan), Dutch (nld), English (eng), Estonian (est), Filipino (fil), Finnish (fin), French (fra), Fulah (ful), Galician (glg), Ganda (lug), Georgian (kat), German (deu), Greek (ell), Gujarati (guj), Hausa (hau), Hebrew (heb), Hindi (hin), Hungarian (hun), Icelandic (isl), Igbo (ibo), Indonesian (ind), Irish (gle), Italian (ita), Japanese (jpn), Javanese (jav), Kabuverdianu (kea), Kannada (kan), Kazakh (kaz), Khmer (khm), Korean (kor), Kurdish (kur), Kyrgyz (kir), Lao (lao), Latvian (lav), Lingala (lin), Lithuanian (lit), Luo (luo), Luxembourgish (ltz), Macedonian (mkd), Malay (msa), Malayalam (mal), Maltese (mlt), Mandarin Chinese (zho), Māori (mri), Marathi (mar), Mongolian (mon), Nepali (nep), Northern Sotho (nso), Norwegian (nor), Occitan (oci), Odia (ori), Pashto (pus), Persian (fas), Polish (pol), Portuguese (por), Punjabi (pan), Romanian (ron), Russian (rus), Serbian (srp), Shona (sna), Sindhi (snd), Slovak (slk), Slovenian (slv), Somali (som), Spanish (spa), Swahili (swa), Swedish (swe), Tamil (tam), Tajik (tgk), Telugu (tel), Thai (tha), Turkish (tur), Ukrainian (ukr), Umbundu (umb), Urdu (urd), Uzbek (uzb), Vietnamese (vie), Welsh (cym), Wolof (wol), Xhosa (xho) and Zulu (zul).*

### Breakdown of language support

Word Error Rate (WER) is a key metric used to evaluate the accuracy of transcription systems. It measures how many errors are present in a transcript compared to a reference transcript. Below is a breakdown of the WER for each language that Scribe v1 and v2 support.

<AccordionGroup>
  <Accordion title="Excellent (≤ 5% WER)">
    Belarusian (bel), Bosnian (bos), Bulgarian (bul), Catalan (cat), Croatian (hrv), Czech (ces),
    Danish (dan), Dutch (nld), English (eng), Estonian (est), Finnish (fin), French (fra), Galician
    (glg), German (deu), Greek (ell), Hungarian (hun), Icelandic (isl), Indonesian (ind), Italian
    (ita), Japanese (jpn), Kannada (kan), Latvian (lav), Macedonian (mkd), Malay (msa), Malayalam
    (mal), Norwegian (nor), Polish (pol), Portuguese (por), Romanian (ron), Russian (rus), Slovak
    (slk), Spanish (spa), Swedish (swe), Turkish (tur), Ukrainian (ukr) and Vietnamese (vie).
  </Accordion>

  <Accordion title="High Accuracy (>5% to ≤10% WER)">
    Armenian (hye), Azerbaijani (aze), Bengali (ben), Cantonese (yue), Filipino (fil), Georgian
    (kat), Gujarati (guj), Hindi (hin), Kazakh (kaz), Lithuanian (lit), Maltese (mlt), Mandarin
    (cmn), Marathi (mar), Nepali (nep), Odia (ori), Persian (fas), Serbian (srp), Slovenian (slv),
    Swahili (swa), Tamil (tam) and Telugu (tel)
  </Accordion>

  <Accordion title="Good (>10% to ≤20% WER)">
    Afrikaans (afr), Arabic (ara), Assamese (asm), Asturian (ast), Burmese (mya), Hausa (hau),
    Hebrew (heb), Javanese (jav), Korean (kor), Kyrgyz (kir), Luxembourgish (ltz), Māori (mri),
    Occitan (oci), Punjabi (pan), Tajik (tgk), Thai (tha), Uzbek (uzb) and Welsh (cym).
  </Accordion>

  <Accordion title="Moderate (>25% to ≤50% WER)">
    Amharic (amh), Ganda (lug), Igbo (ibo), Irish (gle), Khmer (khm), Kurdish (kur), Lao (lao),
    Mongolian (mon), Northern Sotho (nso), Pashto (pus), Shona (sna), Sindhi (snd), Somali (som),
    Urdu (urd), Wolof (wol), Xhosa (xho), Yoruba (yor) and Zulu (zul).
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use speech to text API with video files?">
    Yes, the API supports uploading both audio and video files for transcription.
  </Accordion>

  <Accordion title="What are the file size and duration limits for the Speech to Text API?">
    Files up to 3 GB in size and up to 10 hours in duration are supported.
  </Accordion>

  <Accordion title="Which audio and video formats are supported in the API?">
    The API supports the following audio and video formats:

    * audio/aac
    * audio/x-aac
    * audio/x-aiff
    * audio/ogg
    * audio/mpeg
    * audio/mp3
    * audio/mpeg3
    * audio/x-mpeg-3
    * audio/opus
    * audio/wav
    * audio/x-wav
    * audio/webm
    * audio/flac
    * audio/x-flac
    * audio/mp4
    * audio/aiff
    * audio/x-m4a

    Supported video formats include:

    * video/mp4
    * video/x-msvideo
    * video/x-matroska
    * video/quicktime
    * video/x-ms-wmv
    * video/x-flv
    * video/webm
    * video/mpeg
    * video/3gpp
  </Accordion>

  <Accordion title="When will you support more languages?">
    ElevenLabs is constantly expanding the number of languages supported by our models. Please check back frequently for updates.
  </Accordion>

  <Accordion title="Does speech to text API support webhooks?">
    Yes, asynchronous transcription results can be sent to webhooks configured in webhook settings in the UI. Learn more in the [webhooks cookbook](/docs/developers/guides/cookbooks/speech-to-text/webhooks).
  </Accordion>

  <Accordion title="Is a multichannel transcription mode supported in the API?">
    Yes, the multichannel [STT](https://elevenlabs.io/speech-to-text) feature allows you to transcribe audio where each channel is processed independently and assigned a speaker ID based on its channel number. This feature supports up to 5 channels. Learn more in the [multichannel transcription cookbook](/docs/developers/guides/cookbooks/speech-to-text/multichannel-transcription).
  </Accordion>

  <Accordion title="How does billing work for the speech to text API?">
    ElevenLabs charges for speech to text based on the duration of the audio sent for transcription. Billing is calculated per hour of audio, with rates varying by tier and model. See the [API pricing page](https://elevenlabs.io/pricing/api?price.section=speech_to_text#pricing-table) for detailed pricing information.
  </Accordion>
</AccordionGroup>


# Eleven Music

> Learn how to create studio-grade music with natural language prompts in any style with ElevenLabs.

## Overview

Eleven Music is a Text to Music model that generates studio-grade music with natural language prompts in any style. It's designed to understand intent and generate complete, context-aware audio based on your goals. The model understands both natural language and musical terminology, providing you with state-of-the-art features:

* Complete control over genre, style, and structure
* Vocals or just instrumental
* Multilingual, including English, Spanish, German, Japanese and more
* Edit the sound and lyrics of individual sections or the whole song

Listen to a sample:

<elevenlabs-audio-player audio-title="Eleven Outta Ten" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/music-eleven-outta-ten.mp3" />

Created in collaboration with labels, publishers, and artists, Eleven Music is cleared for nearly all commercial uses, from film and television to podcasts and social media videos, and from advertisements to gaming. For more information on supported usage across our different plans, [see our music terms](https://elevenlabs.io/music-terms).

## Usage

Eleven Music is available today on the ElevenLabs website, with public API access and integration into our Agents Platform coming soon.

Created in collaboration with labels, publishers, and artists, Eleven Music is cleared for nearly all commercial uses, from film and television to podcasts and social media videos, and from advertisements to gaming. For more information on supported usage across our different plans, head here.

Eleven Music is available today on our website, with public API access and integration into our Agents Platform coming soon. Check out our prompt engineering guide to help you master the full range of the model’s capabilities.

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/products/music">
    Step-by-step guide for using Eleven Music on the ElevenCreative Platform.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/music">
    Step-by-step guide for using Eleven Music with the API.
  </Card>

  <Card title="Prompting guide" icon="duotone book-sparkles" href="/docs/overview/capabilities/music/best-practices">
    Learn how to use Eleven Music with natural language prompts.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the maximum duration for generated music?">
    Generated music has a minimum duration of 3 seconds and a maximum duration of 5 minutes.
  </Accordion>

  <Accordion title="Is there an API available?">
    Yes, refer to the [developer quickstart](/docs/developers/guides/cookbooks/music/quickstart) for
    more information.
  </Accordion>

  <Accordion title="Can I use Eleven Music for my business?">
    Yes, Eleven Music is cleared for nearly all commercial uses, from film and television to
    podcasts and social media videos, and from advertisements to gaming. For more information on
    supported usage across our different plans, [see our music
    terms](https://elevenlabs.io/music-terms).
  </Accordion>

  <Accordion title="What audio formats are supported?">
    Generated audio is provided in MP3 format with professional-grade quality (44.1kHz,
    128-192kbps). Other audio formats will be supported soon.
  </Accordion>
</AccordionGroup>


# Best practices

> Master prompting for Eleven Music to achieve maximum musicality and control.

This guide summarizes the most effective techniques for prompting the Eleven Music model. It covers genre & creativity, instrument & vocal isolation, musical control, and structural timing & lyrics.

The model is designed to understand intent and generate complete, context-aware audio based on your goals. High-level prompts like *"ad for a sneaker brand"* or *"peaceful meditation with voiceover"* are often enough to guide the model toward tone, structure, and content that match your use case.

## Genre & Creativity

The model demonstrates strong adherence to genre conventions and emotional tone. Both musical descriptors of emotional tone and tone descriptors themselves will work. It responds effectively to both:

* Abstract mood descriptors (e.g., "eerie," "foreboding")
* Detailed musical language (e.g., "dissonant violin screeches over a pulsing sub-bass")

Prompt length and detail do not always correlate with better quality outputs. For more creative and unexpected results, try using simple, evocative keywords to let the model interpret and compose freely.

## Instrument & Vocal Isolation

The v1 model does not generate stems directly from a full track. To create stems with greater control, use targeted prompts and structure:

* Use the word "solo" before instruments (e.g., "solo electric guitar," "solo piano in C minor").
* For vocals, use "a cappella" before the vocal description (e.g., "a cappella female vocals," "a cappella male chorus").

To improve stem quality and control:

* Include key, tempo (BPM), and musical tone (e.g., "a cappella vocals in A major, 90 BPM, soulful and raw").
* Be as musically descriptive as possible to guide the model's output.

## Musical Control

The model accurately follows BPM and often captures the intended musical key. To gain more control over timing and harmony, include tempo cues like "130 BPM" and key signatures like "in A minor" in your prompt.

To influence vocal delivery and tone, use expressive descriptors such as "raw," "live," "glitching," "breathy," or "aggressive."

The model can effectively render multiple vocalists, use prompts like "two singers harmonizing in C" to direct vocal arrangement.

In general, more detailed prompts lead to greater control and expressiveness in the output.

## Structural Timing & Lyrics

You can specify the length of the song (e.g., "60 seconds") or use auto mode to let the model determine the duration. If lyrics are not provided, the model will generate structured lyrics that match the chosen or auto-detected length.

By default, most music prompts will include lyrics. To generate music without vocals, add "instrumental only" to your prompt. You can also write your own lyrics for more creative control. The model uses your lyrics in combination with the prompt length to determine vocal structure and placement.

To manage when vocals begin or end, include clear timing cues like:

* "lyrics begin at 15 seconds"
* "instrumental only after 1:45"

The model supports multilingual lyric generation. To change the language of a generated song in our UI, use follow-ups like "make it Japanese" or "translate to Spanish."

## Sample Prompts

The model allows you to move beyond song descriptors and into intent for maximum creativity.

<Tabs>
  <Tab title="Video Game with Musical Control">
    ```text
    Create an intense, fast-paced electronic track for a high-adrenaline video game scene.
    Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and
    aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension,
    quick transitions, and dynamic energy bursts.
    ```
  </Tab>

  <Tab title="Mascara Audio Ad Creative">
    ```text
    Track for a high-end mascara commercial. Upbeat and polished. Voiceover only.
    The script begins: "We bring you the most volumizing mascara yet." Mention the brand
    name "X" at the end.
    ```
  </Tab>

  <Tab title="Live Indie Rock Performance">
    ```text
    Write a raw, emotionally charged track that fuses alternative R&B, gritty soul, indie rock,
    and folk. The song should still feel like a live, one-take, emotionally spontaneous
    performance. A female vocalist begins at 15 seconds:

    "I tried to leave the light on, just in case you turned around
    But all the shadows answered back, and now I'm burning out
    My voice is shaking in the silence you left behind
    But I keep singing to the smoke, hoping love is still alive"
    ```
  </Tab>
</Tabs>


# Text to Dialogue

> Learn how to create immersive, natural-sounding dialogue with ElevenLabs.

## Overview

The ElevenLabs [Text to Dialogue](/docs/api-reference/text-to-dialogue/convert) API creates natural sounding expressive dialogue from text using the Eleven v3 model. Popular use cases include:

* Generating pitch perfect conversations for video games
* Creating immersive dialogue for podcasts and other audio content
* Bring audiobooks to life with expressive narration

Text to Dialogue is not intended for use in real-time applications like conversational agents. Several generations might be required to achieve the desired results. When integrating Text to Dialogue into your application, consider generating several generations and allowing the user to select the best one.

Listen to a sample:

<elevenlabs-audio-player audio-title="Dialogue example" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/dialogue.mp3" />

<CardGroup cols={2}>
  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/text-to-dialogue">
    Learn how to integrate text to dialogue into your application.
  </Card>

  <Card title="Prompting guide" icon="duotone book-sparkles" href="/docs/overview/capabilities/text-to-speech/best-practices#prompting-eleven-v3">
    Learn how to use the Eleven v3 model to generate expressive dialogue.
  </Card>
</CardGroup>

## Voice options

ElevenLabs offers thousands of voices across 70+ languages through multiple creation methods:

* [Voice library](/docs/overview/capabilities/voices) with 3,000+ community-shared voices
* [Professional voice cloning](/docs/overview/capabilities/voices#cloned) for highest-fidelity replicas
* [Instant voice cloning](/docs/overview/capabilities/voices#cloned) for quick voice replication
* [Voice design](/docs/overview/capabilities/voices#voice-design) to generate custom voices from text descriptions

Learn more about our [voice options](/docs/overview/capabilities/voices).

## Prompting

The models interpret emotional context directly from the text input. For example, adding
descriptive text like "she said excitedly" or using exclamation marks will influence the speech
emotion. Voice settings like Stability and Similarity help control the consistency, while the
underlying emotion comes from textual cues.

Read the [prompting guide](/docs/overview/capabilities/text-to-speech/best-practices#prompting-eleven-v3) for more details.

### Emotional deliveries with audio tags

<Warning>
  This feature is still under active development, actual results may vary.
</Warning>

The Eleven v3 model allows the use of non-speech audio events to influence the delivery of the dialogue. This is done by inserting the audio events into the text input wrapped in square brackets.

Audio tags come in a few different forms:

### Emotions and delivery

For example, \[sad], \[laughing] and \[whispering]

### Audio events

For example, \[leaves rustling], \[gentle footsteps] and \[applause].

### Overall direction

For example, \[football], \[wrestling match] and \[auctioneer].

Some examples include:

```
"[giggling] That's really funny!"
"[groaning] That was awful."
"Well, [sigh] I'm not sure what to say."
```

<elevenlabs-audio-player audio-title="Expressive dialogue" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/dialogue-emotive.mp3" />

You can also use punctuation to indicate the flow of dialog, like interruptions:

```
"[cautiously] Hello, is this seat-"
"[jumping in] Free? [cheerfully] Yes it is."
```

<elevenlabs-audio-player audio-title="Interruption" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/dialogue-interruption.mp3" />

Ellipses can be used to indicate trailing sentences:

```
"[indecisive] Hi, can I get uhhh..."
"[quizzically] The usual?"
"[elated] Yes! [laughs] I'm so glad you knew!"
```

<elevenlabs-audio-player audio-title="Ellipses" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/dialogue-ellipses.mp3" />

## Supported formats

The default response format is "mp3", but other formats like "PCM", & "μ-law" are available.

* **MP3**
  * Sample rates: 22.05kHz - 44.1kHz
  * Bitrates: 32kbps - 192kbps
  * 22.05kHz @ 32kbps
  * 44.1kHz @ 32kbps, 64kbps, 96kbps, 128kbps, 192kbps
* **PCM (S16LE)**
  * Sample rates: 16kHz - 44.1kHz
  * Bitrates: 8kHz, 16kHz, 22.05kHz, 24kHz, 44.1kHz, 48kHz
  * 16-bit depth
* **μ-law**
  * 8kHz sample rate
  * Optimized for telephony applications
* **A-law**
  * 8kHz sample rate
  * Optimized for telephony applications
* **Opus**
  * Sample rate: 48kHz
  * Bitrates: 32kbps - 192kbps

<Success>
  Higher quality audio options are only available on paid tiers - see our [pricing
  page](https://elevenlabs.io/pricing/api) for details.
</Success>

## Supported languages

The Eleven v3 model supports 70+ languages, including:

*Afrikaans (afr), Arabic (ara), Armenian (hye), Assamese (asm), Azerbaijani (aze), Belarusian (bel), Bengali (ben), Bosnian (bos), Bulgarian (bul), Catalan (cat), Cebuano (ceb), Chichewa (nya), Croatian (hrv), Czech (ces), Danish (dan), Dutch (nld), English (eng), Estonian (est), Filipino (fil), Finnish (fin), French (fra), Galician (glg), Georgian (kat), German (deu), Greek (ell), Gujarati (guj), Hausa (hau), Hebrew (heb), Hindi (hin), Hungarian (hun), Icelandic (isl), Indonesian (ind), Irish (gle), Italian (ita), Japanese (jpn), Javanese (jav), Kannada (kan), Kazakh (kaz), Kirghiz (kir), Korean (kor), Latvian (lav), Lingala (lin), Lithuanian (lit), Luxembourgish (ltz), Macedonian (mkd), Malay (msa), Malayalam (mal), Mandarin Chinese (cmn), Marathi (mar), Nepali (nep), Norwegian (nor), Pashto (pus), Persian (fas), Polish (pol), Portuguese (por), Punjabi (pan), Romanian (ron), Russian (rus), Serbian (srp), Sindhi (snd), Slovak (slk), Slovenian (slv), Somali (som), Spanish (spa), Swahili (swa), Swedish (swe), Tamil (tam), Telugu (tel), Thai (tha), Turkish (tur), Ukrainian (ukr), Urdu (urd), Vietnamese (vie), Welsh (cym).*

## FAQ

<AccordionGroup>
  <Accordion title="Which models can I use?">
    Text to Dialogue is only available on the Eleven v3 model.
  </Accordion>

  <Accordion title="Do I own the audio output?">
    Yes. You retain ownership of any audio you generate. However, commercial usage rights are only
    available with paid plans. With a paid subscription, you may use generated audio for commercial
    purposes and monetize the outputs if you own the IP rights to the input content.
  </Accordion>

  <Accordion title="What qualifies as a free regeneration?">
    A free regeneration allows you to regenerate the same text to speech content without additional cost, subject to these conditions:

    * Only available within the ElevenLabs dashboard.
    * You can regenerate each piece of content up to 2 times for free.
    * The content must be exactly the same as the previous generation. Any changes to the text, voice settings, or other parameters will require a new, paid generation.

    Free regenerations are useful in case there is a slight distortion in the audio output. According to ElevenLabs' internal benchmarks, regenerations will solve roughly half of issues with quality, with remaining issues usually due to poor training data.
  </Accordion>

  <Accordion title="How many speakers can my dialogue have?">
    There is no limit to the number of speakers in a dialogue.
  </Accordion>

  <Accordion title="Why is my output sometimes inconsistent?">
    The models are nondeterministic. For consistency, use the optional [seed
    parameter](/docs/api-reference/text-to-speech/convert#request.body.seed), though subtle
    differences may still occur.
  </Accordion>

  <Accordion title="What's the best practice for large text conversions?">
    Split long text into segments and use streaming for real-time playback and efficient processing.
  </Accordion>
</AccordionGroup>


# Image & Video

> Generate and edit stunning images and videos from text prompts and visual references.

## Overview

Image & Video enables you to create high-quality visual content from simple text descriptions or reference images. Generate static images or dynamic videos in any style, then refine them iteratively with additional prompts, upscale for high-resolution output, and even add lip-sync with audio.

<Note>
  This feature is currently in beta.
</Note>

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/playground/image-video">
    Complete guide to using Image & Video in ElevenLabs.
  </Card>
</CardGroup>

## Key capabilities

* **Image generation**: Create high-quality images from text prompts or reference images with models optimized for speed or quality
* **Video generation**: Generate dynamic videos with cinematic motion, physics realism, and integrated audio. Video generation is only available on paid plans
* **Iterative refinement**: Refine generations with additional prompts and create variations
* **Enhancement tools**: Upscale resolution by up to 4x and apply realistic lip-sync with audio
* **Multiple models**: Access specialized models for different use cases, from rapid iteration to production-ready content
* **Reference support**: Guide generation with start frames, end frames, and style references. Supports a wide range of image file formats including JPG, PNG, WEBP, and more
* **Export flexibility**: Download as standalone files or import directly into Studio projects

## Workflow

The creation process moves you from inspiration to finished asset in four stages:

**Explore:** Discover community creations to find inspiration and study effective prompts.

**Generate:** Use the prompt box to describe what you want to create, select a model, and fine-tune settings.

**Iterate and enhance:** Review generations, create variations, and apply enhancements like upscaling and lip-syncing.

**Export:** Download finished assets or send them directly to Studio.

## Supported download formats

**Video:**

* **MP4**: Codecs H.264, H.265. Quality up to 4K (with upscaling)

**Image:**

* **PNG**: High-resolution, lossless output

## Models

Image & Video provides access to specialized models optimized for different use cases. Each model offers unique capabilities, from rapid iteration to production-ready quality.

Post-processing models require an existing generated output, though you can also upload your own image or video file.

<AccordionGroup>
  <Accordion title="Video generative models">
    <AccordionGroup>
      <Accordion title="OpenAI Sora 2 Pro">
        The most advanced, high-fidelity video model for cinematic results at your disposal.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Highest-fidelity, professional-grade output with synced audio
        * Precise multi-shot control
        * Excels at complex motion and prompt adherence
        * Fixed durations: 4s, 8s, and 12s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Cinematic, professional-grade video content

        **Cost:** Starts at 12,000 credits for a generation

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound is enabled by default.
        </Note>
      </Accordion>

      <Accordion title="OpenAI Sora 2">
        The standard, high-speed version of OpenAI's advanced video model, tuned for everyday content creation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Realistic, physics-aware videos with synced audio
        * Fine scene control
        * Fixed durations: 4s, 8s, and 12s
        * Batch creation with up to 4 generations at a time
        * Strong narrative and character consistency

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Everyday content creation with realistic physics

        **Cost:** Starts at 4,000 credits for default settings

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound is enabled by default.
        </Note>
      </Accordion>

      <Accordion title="Google Veo 3.1">
        A professional-grade model for high-quality, cinematic video generation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame
        * Image References

        **Features:**

        * Excellent quality and creative control with negative prompts
        * Fully integrated and synchronized audio
        * Realistic dialogue, lip-sync, and sound effects
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time
        * Dedicated sound control

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * High-quality, cinematic video generation with full creative control

        **Cost:** Starts at 8,000 credits for default settings

        <Note>
          Enabling and disabling sound will change the generation credits.
        </Note>
      </Accordion>

      <Accordion title="Kling 2.5">
        A balanced and versatile model for high-quality, full-HD video generation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Excels at simulating complex motion and realistic physics
        * Accurately models fluid dynamics and expressions
        * Fixed durations: 5s and 10s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 1080p
        * Aspect ratios: 16:9, 1:1, 9:16

        **Ideal for:**

        * Realistic physics simulations and complex motion

        **Cost:** Starts at 3,500 credits for default settings

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound control not available.
        </Note>
      </Accordion>

      <Accordion title="Google Veo 3.1 Fast">
        A high-speed model optimized for rapid previews and generations, delivering sharper visuals with lower latency.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame

        **Features:**

        * Advanced creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time
        * Accurately models real-world physics for realistic motion and interactions

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Quick iteration and A/B testing visuals
        * Fast-paced social media content creation

        **Cost:** Starts at 4,000 credits for default settings
      </Accordion>

      <Accordion title="Google Veo 3">
        Production-ready model delivering exceptional quality, strong physics realism, and coherent narrative audio.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Advanced integrated "narrative audio" generation that matches video tone and story
        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Final renders and professional marketing content
        * Short-form storytelling

        **Cost:** Starts at 8,000 credits for default settings
      </Accordion>

      <Accordion title="Google Veo 3 Fast">
        A high-speed, cost-efficient model for generating audio-backed video from text or a starting image.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Rapid iteration and previews
        * Cost-effective content creation

        **Cost:** Starts at 4,000 credits for default settings
      </Accordion>

      <Accordion title="Seedance 1 Pro">
        A specialized model for creating dynamic, multi-shot sequences with large movement and action.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame

        **Features:**

        * Highly stable physics and seamless transitions between shots
        * Fixed durations: 3s, 4s, 5s, 6s, 7s, 8s, 9s, 10s, 11s, and 12s
        * Batch creation with up to 4 generations at a time
        * Maximum creative flexibility with numerous aspect ratio options

        **Output options:**

        * Resolutions: 480p, 720p, 1080p
        * Aspect ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Storytelling and action scenes requiring stable physics

        **Cost:** Starts at 4,800 credits for default settings

        <Note>
          Aspect ratio and resolution do not affect generation credits, but duration does.
        </Note>
      </Accordion>

      <Accordion title="Wan 2.5">
        A versatile model that delivers cinematic motion and high prompt fidelity from text or a starting image.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame (Image-to-Video)

        **Features:**

        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 5s and 10s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 480p, 720p, 1080p
        * Aspect ratios: 16:9, 1:1, 9:16

        **Ideal for:**

        * Cinematic content with strong prompt adherence

        **Cost:** Starts at 2,500 credits for default settings

        <Note>
          Generation cost varies based on selected settings.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Image generative models">
    <AccordionGroup>
      <Accordion title="Google Nano Banana">
        A high-speed model for quick, high-quality image generation and editing directly from text prompts.

        **Features:**

        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16

        **Ideal for:**

        * Rapid image creation and iteration

        **Cost:** Starts at 2,000 credits for default settings; varies based on number of generations
      </Accordion>

      <Accordion title="Seedream 4">
        A specialized image model for generating multi-shot sequences or scenes with large movement and action.

        **Features:**

        * Excels at creating images with stable physics and coherent transitions
        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: auto, 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Action scenes and dynamic compositions

        **Cost:** Starts at 1,200 credits for default settings; varies based on number of generations
      </Accordion>

      <Accordion title="Flux 1 Kontext Pro">
        A professional model for advanced image generation and editing, offering strong scene coherence and style control.

        **Features:**

        * Image-based style control requiring a reference image to guide visual aesthetic
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 21:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 9:21

        **Ideal for:**

        * Professional content with precise style requirements

        **Cost:** Starts at 1,600 credits; varies based on settings and number of generations
      </Accordion>

      <Accordion title="Wan 2.5">
        An image model with strong prompt fidelity and motion awareness, ideal for capturing dynamic action in a still frame.

        **Features:**

        * Granular control with negative prompts
        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Dynamic still images with motion awareness

        **Cost:** Starts at 2,000 credits; varies based on settings
      </Accordion>

      <Accordion title="OpenAI GPT Image 1">
        A versatile model for precise, high-quality image creation and detailed editing guided by natural language prompts.

        **Features:**

        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 3:2, 1:1, 2:3
        * Quality options: low, medium, high

        **Ideal for:**

        * Creating and editing images with precise, text-based control

        **Cost:** Starts at 2,400 credits for default settings; varies based on settings and number of generations
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Lip-sync models">
    <AccordionGroup>
      <Accordion title="Omnihuman 1.5">
        A dedicated utility model for generating exceptionally realistic, humanlike lip-sync.

        **Inputs:**

        * Static source image
        * Speech audio file

        **Features:**

        * Animates the mouth on the source image to match provided audio
        * Creates high-fidelity "talking" video from still images
        * Lip-sync specific tool, not a full video generation model

        **Ideal for:**

        * Creating talking avatars
        * Adding dialogue to still images
        * Professional dubbing workflows

        **Cost:** Depends on generation input

        <Note>
          For best results, the image should contain a detectable figure.
        </Note>
      </Accordion>

      <Accordion title="Veed LipSync">
        A fast, affordable, and precise utility model for applying realistic lip-sync to videos.

        **Inputs:**

        * Source video
        * New speech audio file

        **Features:**

        * Re-animates mouth movements in source video to match new audio
        * Video-to-video lip-sync tool, not a full video generator

        **Ideal for:**

        * High-volume, cost-effective dubbing
        * Translating content
        * Correcting audio in video clips with realistic results

        **Cost:** Depends on generation input

        <Note>
          For best results, the video should contain a detectable figure.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Upscaling model">
    <AccordionGroup>
      <Accordion title="Topaz Upscale">
        A dedicated utility model for image and video upscaling, designed to enhance resolution and detail up to 4x.

        **Features:**

        * Enhancement tool that processes existing media
        * Increases media size while preserving natural textures and minimizing artifacts
        * Highly granular upscale factors: 1x, 1.25x, 1.5x, 1.75x, 2x, 3x, 4x
        * Video-specific: Flexible frame rate control (keep source or convert to 24, 25, 30, 48, 50, or 60 fps)

        **Ideal for:**

        * Improving quality of generated media
        * Restoring legacy footage or photos
        * Preparing assets for high-resolution displays

        **Cost:** Depends on generation input
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>


# Voice changer

> Learn how to transform audio between voices while preserving emotion and delivery.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/d3B3BiCmczc" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

ElevenLabs [voice changer](/docs/api-reference/speech-to-speech/convert) API lets you transform any source audio (recorded or uploaded) into a different, fully cloned voice without losing the performance nuances of the original. It’s capable of capturing whispers, laughs, cries, accents, and subtle emotional cues to achieve a highly realistic, human feel and can be used to:

* Change any voice while preserving emotional delivery and nuance
* Create consistent character voices across multiple languages and recording sessions
* Fix or replace specific words and phrases in existing recordings

Explore our [voice library](https://elevenlabs.io/voice-library) to find the perfect voice for your project.

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/playground/voice-changer">
    Step-by-step guide for using voice changer in ElevenLabs.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/voice-changer">
    Learn how to integrate voice changer into your application.
  </Card>
</CardGroup>

## Supported languages

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

The `eleven_english_sts_v2` model only supports English.

## Best practices

### Audio quality

* Record in a quiet environment to minimize background noise
* Maintain appropriate microphone levels - avoid too quiet or peaked audio
* Use `remove_background_noise=true` if environmental sounds are present

### Recording guidelines

* Keep segments under 5 minutes for optimal processing
* Feel free to include natural expressions (laughs, sighs, emotions)
* The source audio's accent and language will be preserved in the output

### Parameters

* **Style**: Set to 0% when input audio is already expressive
* **Stability**: Use 100% for maximum voice consistency
* **Language**: Choose source audio that matches your desired accent and language

## FAQ

<AccordionGroup>
  <Accordion title="Can I convert more than 5 minutes of audio?">
    Yes, but you must split it into smaller chunks (each under 5 minutes). This helps ensure stability
    and consistent output.
  </Accordion>

  <Accordion title="Can I use my own custom/cloned voice for output?">
    Absolutely. Provide your custom voice’s <code>voice\_id</code> and specify the correct{' '}
    <code>model\_id</code>.
  </Accordion>

  <Accordion title="How is billing handled?">
    You’re charged at 1000 characters’ worth of usage per minute of processed audio. There’s no
    additional fee based on file size.
  </Accordion>

  <Accordion title="Does the model reproduce background noise?">
    Possibly. Use <code>remove\_background\_noise=true</code> or the Voice Isolator tool to minimize
    environmental sounds in the final output.
  </Accordion>

  <Accordion title="Which model is best for English audio?">
    Though <code>eleven\_english\_sts\_v2</code> is available, our{' '}
    <code>eleven\_multilingual\_sts\_v2</code> model often outperforms it, even for English material.
  </Accordion>

  <Accordion title="How does style & stability work?">
    “Style” adds interpretative flair; “stability” enforces consistency. For high-energy performances
    in the source audio, turn style down and stability up.
  </Accordion>
</AccordionGroup>


# Voice isolator

> Learn how to isolate speech from background noise, music, and ambient sounds from any audio.

## Overview

ElevenLabs [voice isolator](/docs/api-reference/audio-isolation/convert) API transforms audio recordings with background noise into clean, studio-quality speech. This is particularly useful for audio recorded in noisy environments, or recordings containing unwanted ambient sounds, music, or other background interference.

Listen to a sample:

<CardGroup cols={2}>
  <elevenlabs-audio-player audio-title="Original audio" audio-src="https://eleven-public-cdn.elevenlabs.io/audio/voice-isolator/voice-isolator-promo-original.mp3" />

  <elevenlabs-audio-player audio-title="Isolated audio" audio-src="https://eleven-public-cdn.elevenlabs.io/audio/voice-isolator/voice-isolator-promo-isolated.mp3" />
</CardGroup>

## Usage

The voice isolator model extracts speech from background noise in both audio and video files.

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/audio-tools/voice-isolator">
    Step-by-step guide for using voice isolator in ElevenLabs.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/voice-isolator">
    Learn how to integrate voice isolator into your application.
  </Card>
</CardGroup>

### Supported file types

* **Audio**: AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A
* **Video**: MP4, AVI, MKV, MOV, WMV, FLV, WEBM, MPEG, 3GPP

## FAQ

* **Cost**: Voice isolator costs 1000 characters for every minute of audio.
* **File size and length**: Supports files up to 500MB and 1 hour in length.
* **Music vocals**: Not specifically optimized for isolating vocals from music, but may work depending on the content.


# Dubbing

> Learn how to translate audio and video while preserving the emotion, timing & tone of speakers.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/RKzp4OfCgBA" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

ElevenLabs [dubbing](/docs/api-reference/dubbing/create) API translates audio and video across 32 languages while preserving the emotion, timing, tone and unique characteristics of each speaker. Our model separates each speaker’s dialogue from the soundtrack, allowing you to recreate the original delivery in another language. It can be used to:

* Grow your addressable audience by 4x to reach international audiences
* Adapt existing material for new markets while preserving emotional nuance
* Offer content in multiple languages without re-recording voice talent

We also offer a [fully managed dubbing service](https://elevenlabs.io/elevenstudios) for video and podcast creators.

## Usage

ElevenLabs dubbing can be used in three ways:

* **Dubbing Studio** in the user interface for fast, interactive control and editing
* **Programmatic integration** via our [API](/docs/api-reference/dubbing/create) for large-scale or automated workflows
* **Human-verified dubs via ElevenLabs Productions** - for more information, please reach out to [productions@elevenlabs.io](mailto:productions@elevenlabs.io)

The UI supports files up to **500MB** and **45 minutes**. The API supports files up to **1GB** and **2.5 hours**.

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/products/dubbing/dubbing-studio">
    Edit transcripts and translate videos step by step in Dubbing Studio.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/dubbing">
    Learn how to integrate dubbing into your application.
  </Card>
</CardGroup>

### Key features

**Speaker separation**
Automatically detect multiple speakers, even with overlapping speech.

**Multi-language output**
Generate localized tracks in 32 languages.

**Preserve original voices**
Retain the speaker’s identity and emotional tone.

**Keep background audio**
Avoid re-mixing music, effects, or ambient sounds.

**Customizable transcripts**
Manually edit translations and transcripts as needed.

**Supported file types**
Videos and audio can be dubbed from various sources, including YouTube, X, TikTok, Vimeo, direct URLs, or file uploads.

**Video transcript and translation editing**
Our AI video translator lets you manually edit transcripts and translations to ensure your content is properly synced and localized. Adjust the voice settings to tune delivery, and regenerate speech segments until the output sounds just right.

<Note>
  A Creator plan or higher is required to dub audio files. For videos, a watermark option is
  available to reduce credit usage.
</Note>

### Cost

To reduce credit usage, you can:

* Dub only a selected portion of your file
* Use watermarks on video output (not available for audio)
* Fine-tune transcripts and regenerate individual segments instead of the entire clip

Refer to our [pricing page](https://elevenlabs.io/pricing) for detailed credit costs.

## List of supported languages for dubbing

| No | Language Name | Language Code |
| -- | ------------- | ------------- |
| 1  | English       | en            |
| 2  | Hindi         | hi            |
| 3  | Portuguese    | pt            |
| 4  | Chinese       | zh            |
| 5  | Spanish       | es            |
| 6  | French        | fr            |
| 7  | German        | de            |
| 8  | Japanese      | ja            |
| 9  | Arabic        | ar            |
| 10 | Russian       | ru            |
| 11 | Korean        | ko            |
| 12 | Indonesian    | id            |
| 13 | Italian       | it            |
| 14 | Dutch         | nl            |
| 15 | Turkish       | tr            |
| 16 | Polish        | pl            |
| 17 | Swedish       | sv            |
| 18 | Filipino      | fil           |
| 19 | Malay         | ms            |
| 20 | Romanian      | ro            |
| 21 | Ukrainian     | uk            |
| 22 | Greek         | el            |
| 23 | Czech         | cs            |
| 24 | Danish        | da            |
| 25 | Finnish       | fi            |
| 26 | Bulgarian     | bg            |
| 27 | Croatian      | hr            |
| 28 | Slovak        | sk            |
| 29 | Tamil         | ta            |

## FAQ

<AccordionGroup>
  <Accordion title="What content can I dub?">
    Dubbing can be performed on all types of short and long form video and audio content. We
    recommend dubbing content with a maximum of 9 unique speakers at a time to ensure a high-quality
    dub.
  </Accordion>

  <Accordion title="Does dubbing preserve the speaker's natural intonation?">
    Yes. Our models analyze each speaker’s original delivery to recreate the same tone, pace, and
    style in your target language.
  </Accordion>

  <Accordion title="What about overlapping speakers or background noise?">
    We use advanced source separation to isolate individual voices from ambient sound. Multiple
    overlapping speakers can be split into separate tracks.
  </Accordion>

  <Accordion title="Are there file size limits?">
    Via the user interface, the maximum file size is 1GB up to 45 minutes. Through the API, you can
    process files up to 1GB and 2.5 hours.
  </Accordion>

  <Accordion title="How do I handle fine-tuning or partial translations?">
    You can choose to dub only certain portions of your video/audio or tweak translations/voices in
    our interactive Dubbing Studio.
  </Accordion>
</AccordionGroup>


# Sound effects

> Learn how to create high-quality sound effects from text with ElevenLabs.

## Overview

ElevenLabs [sound effects](/docs/api-reference/text-to-sound-effects/convert) API turns text descriptions into high-quality audio effects with precise control over timing, style and complexity. The model understands both natural language and audio terminology, enabling you to:

* Generate cinematic sound design for films & trailers
* Create custom sound effects for games & interactive media
* Produce Foley and ambient sounds for video content

Listen to an example:

<elevenlabs-audio-player audio-title="Cinematic braam" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/sfx-cinematic-braam.mp3" />

## Usage

Sound effects are generated using text descriptions & two optional parameters:

* **Duration**: Set a specific length for the generated audio (in seconds)

  * Default: Automatically determined based on the prompt
  * Range: 0.1 to 30 seconds
  * Cost: 40 credits per second when duration is specified

* **Looping**: Enable seamless looping for sound effects longer than 30 seconds

  * Creates sound effects that can be played on repeat without perceptible start/end points
  * Perfect for atmospheric sounds, ambient textures, and background elements
  * Example: Generate 30s of 'soft rain' then loop it endlessly for atmosphere in audiobooks, films, games

* **Prompt influence**: Control how strictly the model follows the prompt

  * High: More literal interpretation of the prompt
  * Low: More creative interpretation with added variations

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/playground/sound-effects">
    Step-by-step guide for using sound effects in ElevenLabs.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/sound-effects">
    Learn how to integrate sound effects into your application.
  </Card>
</CardGroup>

### Prompting guide

#### Simple effects

For basic sound effects, use clear, concise descriptions:

* "Glass shattering on concrete"
* "Heavy wooden door creaking open"
* "Thunder rumbling in the distance"

<elevenlabs-audio-player audio-title="Wood chopping" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/sfx-wood-chopping.mp3" />

#### Complex sequences

For multi-part sound effects, describe the sequence of events:

* "Footsteps on gravel, then a metallic door opens"
* "Wind whistling through trees, followed by leaves rustling"
* "Sword being drawn, then clashing with another blade"

<elevenlabs-audio-player audio-title="Walking and then falling" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/sfx-walking-falling.mp3" />

#### Musical elements

The API also supports generation of musical components:

* "90s hip-hop drum loop, 90 BPM"
* "Vintage brass stabs in F minor"
* "Atmospheric synth pad with subtle modulation"

<elevenlabs-audio-player audio-title="90s drum loop" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/sfx-90s-drum-loop.mp3" />

#### Audio Terminology

Common terms that can enhance your prompts:

* **Impact**: Collision or contact sounds between objects, from subtle taps to dramatic crashes
* **Whoosh**: Movement through air effects, ranging from fast and ghostly to slow-spinning or rhythmic
* **Ambience**: Background environmental sounds that establish atmosphere and space
* **One-shot**: Single, non-repeating sound
* **Loop**: Repeating audio segment
* **Stem**: Isolated audio component
* **Braam**: Big, brassy cinematic hit that signals epic or dramatic moments, common in trailers
* **Glitch**: Sounds of malfunction, jittering, or erratic movement, useful for transitions and sci-fi
* **Drone**: Continuous, textured sound that creates atmosphere and suspense

## FAQ

<AccordionGroup>
  <Accordion title="What's the maximum duration for generated effects?">
    The maximum duration is 30 seconds per generation. For longer sequences, you can either generate
    multiple effects and combine them, or use the looping feature to create seamless repeating sound
    effects.
  </Accordion>

  <Accordion title="Can I generate music with this API?">
    Yes, you can generate musical elements like drum loops, bass lines, and melodic samples.
    However, for full music production, consider combining multiple generated elements.
  </Accordion>

  <Accordion title="How do I ensure consistent quality?">
    Use detailed prompts, appropriate duration settings, and high prompt influence for more
    predictable results. For complex sounds, generate components separately and combine them.
  </Accordion>

  <Accordion title="What audio formats are supported?">
    Generated audio is provided in MP3 format with professional-grade quality. For WAV downloads of
    non-looping sound effects, audio is delivered at 48kHz sample rate - the industry standard for
    film, TV, video, and game audio, ensuring no resampling is needed for professional workflows.
  </Accordion>

  <Accordion title="How do looping sound effects work?">
    Looping sound effects are designed to play seamlessly on repeat without noticeable start or end
    points. This is perfect for creating continuous atmospheric sounds, ambient textures, or
    background elements that need to play indefinitely. For example, you can generate 30 seconds of
    rain sounds and loop them endlessly for background atmosphere in audiobooks, films, or games.
  </Accordion>
</AccordionGroup>


# Voices

> Learn how to create, customize, and manage voices with ElevenLabs.

## Overview

ElevenLabs provides models for voice creation & customization. The platform supports a wide range of voice options, including voices from our extensive [voice library](https://elevenlabs.io/app/voice-library), voice cloning, and artificially designed voices using text prompts.

### Voice types

* **Community**: Voices shared by the community from the ElevenLabs [voice library](/docs/creative-platform/voices/voice-library).
* **Cloned**: Custom voices created using instant or professional [voice cloning](/docs/creative-platform/voices/voice-cloning).
* **Voice design**: Artificially designed voices created with the [voice design](/docs/creative-platform/voices/voice-design) tool.
* **Default**: Pre-designed, high-quality voices optimized for general use.

<Tip>
  Voices that you personally own, either created with Instant Voice Cloning, Professional Voice
  Cloning, or Voice Design, can be used for [Voice
  Remixing](/docs/overview/capabilities/voice-remixing).
</Tip>

#### Community

The [voice library](/docs/creative-platform/voices/voice-library) contains over 10,000 voices shared by the ElevenLabs community. Use it to:

* Discover unique voices shared by the ElevenLabs community.
* Add voices to your personal collection.
* Share your own voice clones for cash rewards when other paid subscribers use it.

<Success>
  Share your voice with the community, set your terms, and earn cash rewards when others use it.
  We've paid out over **\$14M** already.
</Success>

<Warning>
  The voice library is not available via the API to free tier users.
</Warning>

<CardGroup cols={1}>
  <Card title="Products" icon="duotone book-user" iconPosition="left" href="/docs/creative-platform/voices/voice-library">
    Learn how to use voices from the voice library
  </Card>
</CardGroup>

#### Cloned

Clone your own voice from 30-second samples with Instant Voice Cloning, or create hyper-realistic voices using Professional Voice Cloning.

* **Instant Voice Cloning**: Quickly replicate a voice from short audio samples.
* **Professional Voice Cloning**: Generate professional-grade voice clones with extended training audio.

Voice-captcha technology is used to verify that **all** voice clones are created from your own voice samples.

<Note>
  A Creator plan or higher is required to create voice clones.
</Note>

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" iconPosition="left" href="/docs/creative-platform/voices/voice-cloning">
    Learn how to create instant & professional voice clones
  </Card>

  <Card title="Instant Voice Cloning" icon="duotone code" href="/docs/developers/guides/cookbooks/voices/instant-voice-cloning">
    Clone a voice instantly
  </Card>

  <Card title="Professional Voice Cloning" icon="duotone code" href="/docs/developers/guides/cookbooks/voices/professional-voice-cloning">
    Create a perfect voice clone
  </Card>
</CardGroup>

#### Voice design

With [Voice Design](/docs/creative-platform/voices/voice-design), you can create entirely new voices by specifying attributes like age, gender, accent, and tone. Generated voices are ideal for:

* Realistic voices with nuanced characteristics.
* Creative character voices for games and storytelling.

The voice design tool creates 3 voice previews, simply provide:

* A **voice description** between 20 and 1000 characters.
* A **text** to preview the voice between 100 and 1000 characters.

##### Voice design with Eleven v3

Using the [Eleven v3 model](/docs/overview/models#eleven-v3), voices that are capable of a wide range of emotion can be designed via a prompt.

Using v3 gets you the following benefits:

* More natural and versatile voice generation.
* Better control over voice characteristics.
* Audio tags supported in Preview generations.
* Backward compatibility with v2 models.

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/docs/creative-platform/voices/voice-design">
    Learn how to craft voices from a single prompt.
  </Card>

  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/voices/voice-design">
    Integrate voice design into your application.
  </Card>
</CardGroup>

#### Default

Our curated set of default voices is optimized for core use cases. These voices are:

* **Reliable**: Available long-term.
* **Consistent**: Carefully crafted and quality-checked for performance.
* **Model-ready**: Fine-tuned on new models upon release.

<Info>
  Default voices are available to all users via the **My Voices** tab in the [voice lab
  dashboard](https://elevenlabs.io/app/voice-lab). Default voices were previously referred to as
  `premade` voices. The latter term is still used when accessing default voices via the API.
</Info>

### Managing voices

All voices can be managed through **My Voices**, where you can:

* Search, filter, and categorize voices
* Add descriptions and custom tags
* Organize voices for quick access

Learn how to manage your voice collection in [My Voices documentation](/docs/creative-platform/voices/voice-library#my-voices).

* **Search and Filter**: Find voices using keywords or tags.
* **Preview Samples**: Listen to voice demos before adding them to **My Voices**.
* **Add to Collection**: Save voices for easy access in your projects.

> **Tip**: Try searching by specific accents or genres, such as "Australian narration" or "child-like character."

### Supported languages

All ElevenLabs voices support multiple languages. Experiment by converting phrases like `Hello! こんにちは! Bonjour!` into speech to hear how your own voice sounds across different languages.

ElevenLabs supports voice creation in 32 languages. Match your voice selection to your target region for the most natural results.

* **Default Voices**: Optimized for multilingual use.
* **Generated and Cloned Voices**: Accent fidelity depends on input samples or selected attributes.

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

Flash v2.5 supports 32 languages - all languages from v2 models plus:

*Hungarian, Norwegian & Vietnamese*

[Learn more about our models](/docs/overview/models)

## FAQ

<AccordionGroup>
  <Accordion title="Can I create a custom voice?">
    Yes, you can create custom voices with Voice Design or clone voices using Instant or
    Professional Voice Cloning. Both options are accessible in **My Voices**.
  </Accordion>

  <Accordion title="What is the difference between Instant and Professional Voice Cloning?">
    Instant Voice Cloning uses short audio samples for near-instantaneous voice creation.
    Professional Voice Cloning requires longer samples but delivers hyper-realistic, high-quality
    results.
  </Accordion>

  <Accordion title="Can I share my created voices?">
    Professional Voice Clones can be shared privately or publicly in the Voice Library. Generated
    voices and Instant Voice Clones cannot currently be shared.
  </Accordion>

  <Accordion title="How do I manage my voices?">
    Use **My Voices** to search, filter, and organize your voice collection. You can also delete,
    tag, and categorize voices for easier management.
  </Accordion>

  <Accordion title="How can I ensure my cloned voice matches the original?">
    Use clean and consistent audio samples. For Professional Voice Cloning, provide a variety of
    recordings in the desired speaking style.
  </Accordion>

  <Accordion title="Can I share voices I create?">
    Yes, Professional Voice Clones can be shared in the Voice Library. Instant Voice Clones and
    Generated Voices cannot currently be shared.
  </Accordion>

  <Accordion title="What are some common use cases for Generated Voices?">
    Generated Voices are ideal for unique characters in games, animations, and creative
    storytelling.
  </Accordion>

  <Accordion title="How do I access the Voice Library?">
    Go to **Voices > Voice Library** in your dashboard or access it via API.
  </Accordion>
</AccordionGroup>


# Voice remixing

> Learn how to transform and enhance existing voices by modifying their attributes including gender, accent, style, pacing, audio quality, and more.

<Warning>
  Voice remixing is currently in alpha.
</Warning>

## Overview

ElevenLabs voice remixing is available on the core platform and via API. This feature transforms existing voices by allowing you to modify their core attributes while maintaining the unique characteristics that make them recognizable. This is particularly useful for adapting voices to different contexts, creating variations for different characters, or improving and/or changing the audio quality of existing voice profiles.

As an example, here is an original voice:

<elevenlabs-audio-player audio-title="Original voice" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/remix-original-voice.mp3" />

And here is a remixed version, switching to a San Francisco accent:

<elevenlabs-audio-player audio-title="Remixed voice" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/remix-sf-accent.mp3" />

## Usage

The voice remixing model allows you to iteratively transform voices you own by adjusting multiple attributes through natural language prompts and customizable settings.

<CardGroup cols={1}>
  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/voices/remix-a-voice">
    Integrate voice remixing into your application.
  </Card>
</CardGroup>

### Key Features

* **Attribute Modification**: Change gender, accent, speaking style, pacing, and audio quality of any voice you own
* **Iterative Editing**: Continue refining voices based on previously remixed versions
* **Script Flexibility**: Use default scripts or input custom scripts with v3 model audio tags like `[laughs]` or `[whispers]`
* **Prompt Strength Control**: Adjust remix intensity from low to high for precise control over transformations

### Remixing parameters

#### Prompt Strength

Voice remixing offers varying degrees of prompt strength to control how much your voice transforms:

* **Low**: Subtle changes that maintain most of the original voice characteristics
* **Medium**: Balanced transformation that modifies key attributes while preserving voice identity
* **High**: Strong adherence to remix prompt, may significantly change the tonality of the original voice
* **Max**: A full transformation of the voice, but at the cost of changing the voice entirely

#### Script Options

* **Default Scripts**: Pre-configured scripts optimized for voice remixing
* **Custom Scripts**: Input your own text with support for v3 model audio tags such as:
  * `[laughs]` - Add laughter
  * `[whispers]` - Convert to whispered speech
  * `[sighs]` - Add sighing
  * Additional emotion and style tags supported which can help craft the voice

### Tips and Tricks

#### Getting Started

Start with a high prompt strength early in your experimentation to understand the full range of transformation possibilities. You’ll need to have a voice to start with, if you haven’t already created a voice, experiment with default voices available in your library to understand how different base voices respond to remixing.

You can create custom voices using [Voice Design](/docs/creative-platform/voices/voice-design) as starting points for unique remixes.

#### Advanced Techniques

* **Iterative refinement**: Sometimes multiple iterations are needed to achieve the desired voice quality. Each remix can serve as the base for the next transformation
* **Combine attributes gradually**: When making multiple changes (e.g., accent and pacing), consider applying them in separate iterations for more control
* **Test with varied content**: Different scripts may highlight different aspects of your remixed voice

### Supported Voice Formats

#### Input

* Any cloned voice that you personally own (Instant Voice Clone or Professional Voice Clone)
* Voices created through our Voice Design product

#### Output

* Full-quality voice model in v3 (but backwards compatibility to all other models)
* Iteratively editable voice that can be further remixed

## FAQ

<AccordionGroup>
  <Accordion title="What does Voice Remixing cost?">
    Voice remixing costs are calculated based on the length of the test script used during the
    remixing process.
  </Accordion>

  <Accordion title="Can I remix voices I don't own?">
    No, voice remixing is only available for voices in your personal library that you have ownership
    or appropriate permissions for.
  </Accordion>

  <Accordion title="How many times can I remix a voice?">
    There is no limit to iterative remixing. You can continue refining a voice through multiple
    generations of remixes.
  </Accordion>

  <Accordion title="Will remixing affect my original voice?">
    No, remixing creates a new voice variant. Your original voice remains unchanged and available in
    your library.
  </Accordion>

  <Accordion title="What's the difference between Voice Design and Voice Remixing?">
    Voice Design creates new voices from scratch using text prompts, while Voice Remixing modifies
    existing voices you already own.
  </Accordion>
</AccordionGroup>


# Forced Alignment

> Learn how to turn spoken audio and text into a time-aligned transcript with ElevenLabs.

## Overview

The ElevenLabs [Forced Alignment](/docs/api-reference/forced-alignment/create) API turns spoken audio and text into a time-aligned transcript. This is useful for cases where you have audio recording and a transcript, but need exact timestamps for each word or phrase in the transcript. This can be used for:

* Matching subtitles to a video recording
* Generating timings for an audiobook recording of an ebook

## Usage

The Forced Alignment API can be used by interfacing with the ElevenLabs API directly.

<CardGroup cols={1}>
  <Card title="Developers" icon="duotone code" href="/docs/developers/guides/cookbooks/forced-alignment">
    Learn how to integrate Forced Alignment into your application.
  </Card>
</CardGroup>

## Supported languages

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

## FAQ

<AccordionGroup>
  <Accordion title="What is forced alignment?">
    Forced alignment is a technique used to align spoken audio with text. You provide an audio file and a transcript of the audio file and the API will return a time-aligned transcript.

    It's useful for cases where you have audio recording and a transcript, but need exact timestamps for each word or phrase in the transcript.
  </Accordion>

  <Accordion title="What text input formats are supported?">
    The input text should be a string with no special formatting i.e. JSON.

    Example of good input text:

    ```
    "Hello, how are you?"
    ```

    Example of bad input text:

    ```
    {
        "text": "Hello, how are you?"
    }
    ```
  </Accordion>

  <Accordion title="How much does Forced Alignment cost?">
    Forced Alignment costs the same as the [Speech to Text](https://elevenlabs.io/pricing/api?price.section=speech_to_text#pricing-table) API.
  </Accordion>

  <Accordion title="Does Forced Alignment support diarization?">
    Forced Alignment does not support diarization. If you provide diarized text, the API will likely return unwanted results.
  </Accordion>

  <Accordion title="What is the maximum audio file size for Forced Alignment?">
    The maximum file size for Forced Alignment is 3GB.
  </Accordion>

  <Accordion title="What is the maximum duration for a Forced Alignment input file?">
    For audio files, the maximum duration is 10 hours.

    For the text input, the maximum length is 675k characters.
  </Accordion>
</AccordionGroup>


# Account

> Create and manage your ElevenLabs account to start generating AI audio

To begin using ElevenLabs, you'll need to create an account. Follow these steps:

* **Sign Up**: Visit the [ElevenLabs website](https://elevenlabs.io/app/sign-up) and click on the 'Get started free' button. You can register using your email or through one of the OAuth providers.
* **Verify Email**: Check your email for a verification link from ElevenLabs. Click the link to verify your account.
* **Initial Setup**: After verification, you'll be directed to the Speech Synthesis page where you can start generating audio from text.

**Exercise**: Try out an example to get started or type something, select a voice and click generate!

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7098296148ad1263133ad9506a9e7de7e8a2d40c657222080963cb914a8780cb/assets/images/product-guides/administration/account-creation.png" alt="Account creation exercise" />

You can sign up with traditional email and password or using popular OAuth providers like Google, Facebook, and GitHub.

If you choose to sign up with your email, you will be asked to verify your email address before you can start using the service. Once you have verified your email, you will be taken to the Speech Synthesis page, where you can immediately start using the service. Simply type anything into the box and press “generate” to convert the text into voiceover narration. Please note that each time you press “generate” anywhere on the website, it will deduct credits from your quota.

If you sign up using Google OAuth, your account will be intrinsically linked to your Google account, meaning you will not be able to change your email address, as it will always be linked to your Google email.


# Billing

> Manage your subscription, view pricing plans, and understand how credit rollover works

<CardGroup>
  <Card title="Pricing" href="https://elevenlabs.io/pricing">
    View the pricing page
  </Card>

  <Card title="Subscription details" href="https://elevenlabs.io/app/subscription">
    View your subscription details
  </Card>
</CardGroup>

When signing up, you will be automatically assigned to the free tier. To view your subscription, click on your profile icon in the top right corner and select ["Subscription"](https://elevenlabs.io/app/subscription). You can read more about the different plans [here](https://elevenlabs.io/pricing). At the bottom of the page, you will find a comparison table to understand the differences between the various plans.

We offer five public plans: Free, Starter, Creator, Pro, Scale, and Business. In addition, we also offer an Enterprise option that's specifically tailored to the unique needs and usage of large organizations.

You can see details of all our plans on the subscription page. This includes information about the total monthly credit quota, the number of custom voices you can have saved simultaneously, and the quality of audio produced.

Cloning is only available on the Starter tier and above. The free plan offers three custom voices that you can create using our [Voice Design tool](/docs/creative-platform/voices/voice-design), or you can add voices from the [Voice Library](/docs/creative-platform/voices/voice-library) if they are not limited to the paid tiers.

You can upgrade your subscription at any time, and any unused quota from your previous plan will roll over to the new one. As long as you don’t cancel or downgrade, unused credits at the end of the month will carry over to the next month, up to a maximum of two months’ worth of credits. For more information, please visit our Help Center articles:

* ["How does credit rollover work?"](https://help.elevenlabs.io/hc/en-us/articles/27561768104081-How-does-credit-rollover-work)
* ["What happens to my subscription and quota at the end of the month?"](https://help.elevenlabs.io/hc/en-us/articles/13514114771857-What-happens-to-my-subscription-and-quota-at-the-end-of-the-month)

From the [subscription page](https://elevenlabs.io/app/subscription), you can also downgrade your subscription at any point in time if you would like. When downgrading, it won't take effect until the current cycle ends, ensuring that you won't lose any of the monthly quota before your month is up.

When generating content on our paid plans, you get commercial rights to use that content. If you are on the free plan, you can use the content non-commercially with attribution. Read more about the license in our [Terms of Service](https://elevenlabs.io/terms-of-use) and in our Help Center [here](https://help.elevenlabs.io/hc/en-us/articles/13313564601361-Can-I-publish-the-content-I-generate-on-the-platform).

For more information on payment methods, please refer to the [Help Center](https://help.elevenlabs.io/).


# Consolidated billing

> Manage multiple workspaces with unified billing and shared credit pools.

<Info>
  Consolidated billing is an Enterprise feature that allows you to link multiple workspaces under a
  single billing account.
</Info>

## Overview

Consolidated billing enables you to manage multiple workspaces across different environments while maintaining a single billing account.
This feature is particularly useful for organizations that need to operate in multiple regions or maintain separate workspaces for different teams while keeping billing centralized.

With consolidated billing, you have:

* **Unified billing** – Receive a single invoice for all linked workspaces.
* **Shared credit pools** – All workspaces share the same credit allocation.
* **Cross-environment support** – Link workspaces from isolated environments (e.g., EU, India) to the US billing workspace.
* **Independent management** – Each workspace maintains its own members, SSO configurations, and settings.

## How it works

Consolidated billing creates a relationship between workspaces where one workspace (the "billing workspace") receives usage reports from other workspaces (the "reporting workspaces"). All usage is then billed through the billing workspace.

### Billing workspace

The billing workspace must be located in the US environment (`elevenlabs.io`). This workspace:

* Receives usage reports from all linked workspaces.
* Issues a single monthly invoice.
* Shows general usage coming from each reporting workspace.

### Reporting workspaces

Reporting workspaces can be located on elevenlabs.io or in an isolated environment. These workspaces:

* Report their usage to the billing workspace.
* Maintain their own members and configurations.
* Show, as usual, granular usage analytics for that workspace.

<Note>
  Within the same region, users cannot be members of multiple workspaces. This limitation only
  applies within the same environment.
</Note>

## Setup process

Consolidated billing is an Enterprise feature that requires configuration by our team. To enable consolidated billing for your organization, contact your dedicated Customer Success Manager.

## Usage tracking

The billing workspace will be able to see the usage of all linked workspaces.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1b4a2896939345df00263961ea080724f268655a4b258c6988b7344cb3c6ebb0/assets/images/product-guides/administration/consolidated-billing-reporting.png" alt="Consolidated billing reporting view" />

The reporting workspace will only be able to see analytics for its own usage. However, the total credits left shown in the sidebar will be the sum of all linked workspaces.

## FAQ

<AccordionGroup>
  <Accordion title="Can I set credit limits for each workspace?">
    No, all workspaces share the same credit pool. However, you can closely track the usage of each
    workspace.
  </Accordion>

  <Accordion title="Can I have different subscription tiers for different workspaces?">
    No, all workspaces must share the same subscription. The billing workspace determines the
    subscription level for all linked workspaces.
  </Accordion>

  <Accordion title="Can I unlink a workspace from consolidated billing?">
    Yes, you can disable consolidated billing on any reporting workspace. This will require setting
    up a new subscription for that workspace or removing that workspace entirely. To do so, get in
    touch with your dedicated Customer Success Manager.
  </Accordion>

  <Accordion title="Can both workspaces be located on elevenlabs.io?">
    Yes, both workspaces can be located on elevenlabs.io - this is useful if you want to have
    multiple segregated teams. Sharing resources between workspaces is not possible so consider
    using permissions with [user groups](/docs/overview/administration/workspaces/user-groups)
    before enabling consolidated billing.
  </Accordion>
</AccordionGroup>


# Data residency

> Store your data in specific jurisdictions with ElevenLabs' isolated environments.

<Info>
  Data residency is an Enterprise feature. For details on enabling this for your organization,
  please see the "Getting Access" section below.
</Info>

## Overview

ElevenLabs offers "data residency" through isolated environments in certain jurisdictions, allowing customers to limit data storage to those locations. As a standard, ElevenLabs' customer data is hosted/stored in the U.S., however ElevenLabs has released additional storage locations in the EU and India.

Depending on the customer's location, isolated environments in a particular region may also provide the benefit of reduced latency.

## Data residency in isolated environments

ElevenLabs offers data residency in certain jurisdictions to allow customers to choose where their data is stored. While storage will take place in the selected location, processing may nevertheless occur outside of the selected location, including by ElevenLabs' international affiliates and subprocessors, for support purposes, and for content moderation purposes. This detail is captured within ElevenLabs' Data Processing Agreement.

In certain locations, configurations may be available to limit processing to the selected residency location. For example, with respect to EU residency, users may restrict processing to the EU by using Zero Retention Mode and the API. In such case, content submitted to the Service will not be processed outside of the EU, provided the use of certain optional integrations (ex. Custom LLMs or post-call webhooks that require out-of-region processing) may result in processing outside of such jurisdiction.

## Existing core compliance features

Isolated environments complement ElevenLabs' existing suite of security and compliance measures designed to safeguard customer data:

**GDPR Compliance**: Our platform and practices are designed to align with applicable GDPR requirements, including measures designed to ensure lawful data processing, adherence to data subject rights, and the implementation of appropriate security measures as required by GDPR.

**SOC2 Certification**: ElevenLabs maintains SOC2 certification, demonstrating our commitment to high standards for security, availability and confidentiality.

**Zero Retention Mode (Optional)**: Customers can enable Zero Retention Mode, ensuring that sensitive content and data processed by our models are not retained on ElevenLabs servers. This is a powerful feature for minimizing data footprint.

**End-to-End Encryption**: Data transmitted to and from ElevenLabs models is protected by end-to-end encryption, securing it in transit.

**HIPAA Compliance**: For qualifying healthcare enterprises, ElevenLabs offers Business Associate Agreements (BAAs), which offer additional protections in relation to its HIPAA-Eligible Services.

## Developer considerations

Isolated environments are completely separate ElevenLabs workspaces, available via a different address on the web. As such, you will need to get access to this feature first to be able to sign in to an isolated environment with data residency.

### EU

* **Web**: [https://eu.residency.elevenlabs.io](https://eu.residency.elevenlabs.io)
* **API**: `https://api.eu.residency.elevenlabs.io`
* **WebSockets**: `wss://api.eu.residency.elevenlabs.io`

### India

* **Web**: [https://in.residency.elevenlabs.io](https://in.residency.elevenlabs.io)
* **API**: `https://api.in.residency.elevenlabs.io`
* **WebSockets**: `wss://api.in.residency.elevenlabs.io`

Your account on the isolated environment will be separate to the one on elevenlabs.io, and your workspace will be blank. This means that when using an isolated environment via API, you will need to hit a different API URL with a different API key.

### SDK configuration

When using ElevenLabs SDKs, you can specify the environment to connect to an isolated region. Below are examples for each SDK.

<Tabs>
  <Tab title="Python">
    ```python
    from elevenlabs import ElevenLabs, ElevenLabsEnvironment

    # For EU data residency
    client = ElevenLabs(
        api_key="your-api-key",
        environment=ElevenLabsEnvironment.PRODUCTION_EU
    )

    # For India data residency
    client = ElevenLabs(
        api_key="your-api-key",
        environment=ElevenLabsEnvironment.PRODUCTION_IN
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript
    import { ElevenLabsClient, ElevenLabsEnvironment } from "@elevenlabs/elevenlabs-js";

    // For EU data residency
    const client = new ElevenLabsClient({
      apiKey: "your-api-key",
      environment: ElevenLabsEnvironment.ProductionEu,
    });

    // For India data residency
    const client = new ElevenLabsClient({
      apiKey: "your-api-key",
      environment: ElevenLabsEnvironment.ProductionIn,
    });
    ```
  </Tab>

  <Tab title="JavaScript (client)">
    ```javascript
    import { Conversation } from "@elevenlabs/client";

    // For EU data residency
    const conversation = await Conversation.startSession({
      agentId: "<your-agent-id>",
      origin: "https://api.eu.residency.elevenlabs.io",
      // Required when using WebRTC transport
      livekitUrl: "wss://livekit.rtc.eu.residency.elevenlabs.io"
    });

    // For India data residency
    const conversation = await Conversation.startSession({
      agentId: "<your-agent-id>",
      origin: "https://api.in.residency.elevenlabs.io",
      // Required when using WebRTC transport
      livekitUrl: "wss://livekit.rtc.in.residency.elevenlabs.io"
    });
    ```
  </Tab>

  <Tab title="React">
    ```tsx
    import { useConversation } from "@elevenlabs/react";

    // For EU data residency
    const conversation = useConversation({
      serverLocation: "eu-residency",
    });

    // For India data residency
    const conversation = useConversation({
      serverLocation: "in-residency",
    });
    ```

    For more details on the React SDK, see the [React SDK documentation](/docs/agents-platform/libraries/react#data-residency).
  </Tab>
</Tabs>

## Limitations

Currently, ElevenLabs provides limited support for migrating your resources from non-isolated to isolated environments. However, you can enable professional voice clone link sharing from a non-isolated environment and add it to your isolated environment; please refer to the FAQ below for instructions.
Reach out to us if you intend to move instant voice clones. For other resources, such as agents in the Agents Platform, we recommend recreation via the API where possible.

Dubbing is not currently available in isolated environments.

### India

* India has limited availability for the LLMs in the Agents Platform. Currently, we support: GPT 4o,
  GLM-4.5-Air, Qwen3-30B, Qwen3-4B and Custom LLMs. All open source models are hosted by ElevenLabs.
* Twilio doesn't currently offer an India routing region for its calls.

## Getting access

Data residency is an exclusive feature available to ElevenLabs' Enterprise customers.

**Existing Enterprise Customers**: If you are an existing Enterprise customer, please contact [success@elevenlabs.io](mailto:success@elevenlabs.io) to discuss enabling an isolated environment for your account.

**New Customers**: Organizations interested in ElevenLabs Enterprise and requiring an isolated environment should contact [sales@elevenlabs.io](mailto:sales@elevenlabs.io) to discuss specific needs and implementation.

## FAQ

<AccordionGroup>
  <Accordion title="Can I run my isolated environment in parallel with the non-isolated one?">
    Yes, it is possible to do this and to bill the usage for both of them on the same invoice. For
    more details on unified billing across multiple workspaces, see [consolidated
    billing](/docs/overview/administration/consolidated-billing).
  </Accordion>

  <Accordion title="How does this relate to GDPR compliance?">
    For customers subject to GDPR, ElevenLabs provides options to limit storage and, in some cases,
    processing to the EU to support customers' compliance efforts.
  </Accordion>

  <Accordion title="Do isolated environments impact API performance?">
    For users inside the isolated environment region, data residency may potentially reduce latency
    due to localized processing. For users outside the isolated environment region, performance is
    expected to remain consistent with our global infrastructure. While there may be benefits as it
    relates to latency, the purpose of these data residency options are not specifically to improve
    latency.
  </Accordion>

  <Accordion title="Is Zero Retention Mode automatically enabled in isolated environments?">
    No, Zero Retention Mode is an optional feature that can be enabled separately, even for accounts
    with data residency. It provides an additional layer of data minimization by preventing storage of
    content on our servers.
  </Accordion>

  <Accordion title="My API requests to the isolated environment are failing">
    Double check that you are using the correct API URL and the correct API key for the account on the
    isolated environment.
  </Accordion>

  <Accordion title="How do I use an isolated environment in the SDK?">
    When you create the ElevenLabs client object, it takes an environment parameter which is by
    default US but you can set it to your desired environment. See the [SDK
    configuration](#sdk-configuration) section above for code examples in Python, TypeScript,
    JavaScript, and React.
  </Accordion>

  <Accordion title="How do I share a PVC from a non-isolated environment to an isolated environment?">
    To share a PVC with an isolated environment, first enable link sharing for that voice. Then copy
    the link, and add the prefix of the isolated environment to the voice link: From:
    `elevenlabs.io/...` → To: `eu.residency.elevenlabs.io/...`
  </Accordion>
</AccordionGroup>


# Usage analytics

> Track your API usage, monitor credit consumption, and analyze account activity

The Developers page provides comprehensive tools to monitor and analyze your platform activity.

To access these tools, navigate to the **Developers** page (found at the bottom of the sidebar in both ElevenAgents and ElevenCreative).

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3e8ea126ff2f8d646b145c52257c7dfdd3271d05abbfce82999b0a96727f965e/assets/images/product-guides/administration/analytics.webp" alt="Usage analytics interface" />

The Developers page includes several tabs:

* **Usage**: View and filter usage data for your account or workspace
* **Analytics**: Collect, view, and filter workspace activity including API requests, usage metrics, and webhooks
* **Request Log**: View and filter specific API requests for debugging and monitoring

If you're part of a multi-seat workspace, you'll see a toggle to switch between data for your account and your workspace.

## Usage tab

The Usage tab allows you to choose from a range of metrics for analysis, including credits, and filter your usage data in a number of different ways.

You can break your usage down by voice, product, or API key. If you're viewing workspace usage, you have additional options allowing you to break usage down by individual user or workspace group.

You can view the data by day, week, month or cumulatively. If you want to be more specific, you can use filters to show only your usage for specific voices, products or API keys.

This feature is quite powerful, allowing you to gain great insights into your usage or understand your customers' usage if you've implemented us in your product.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b95d7c8edd7ad5e94cb97b443850e54ef84e9d3bc8e844d65e04d1b3a06f050b/assets/images/product-guides/administration/analytics-credits-voice.webp" alt="Usage metrics broken down by voice" />

In the API Requests section, you’ll find not only the total number of requests made within a specific timeframe but also the number of concurrent requests during that period.

You can view data by different time periods, for example, hour, day, month and year, and at different levels of granularity.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/03c5a1eba19089ce5a094b115619d5ae8e9397b4f4bfebcc17f5c7d62f153e24/assets/images/product-guides/administration/analytics-workspace-api.webp" alt="API requests for specified time period" />

## Analytics tab

The Analytics tab provides detailed insights into workspace API requests and webhooks. You can filter and analyze data by different time periods (hour, day, month, year) and at different levels of granularity. You can also monitor success rate and average latency for your API requests.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/93993cf042c491a549cffc330357f3aaf272802f037e867e69e32ad27d5505f1/assets/images/product-guides/administration/analytics-requests.webp" alt="Workspace API calls broken down by path" />

## Request Log

The Request Log tab allows you to view and filter specific API requests for debugging and monitoring purposes.

## Export data

You also have the option to export your data as a CSV file. To do this, just click the "Export as CSV" button, and the data from your current view will be exported and downloaded.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6d41a16a9e09de52a0c9406fe8b02d874e773da2b49f1f0f8c635f9ecda1bc6f/assets/images/product-guides/administration/analytics-export.webp" alt="Export your usage data as CSV" />


# Workspaces

> An overview on how teams can collaborate in a shared workspace.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7623fe79ed73fc788b7814694e0f1e27457878b0f34acb8b3b409d5f257bceae/assets/images/product-guides/administration/workspaces.webp" alt="Workspaces" />

<Info>
  Multi seat workspaces are currently only available for Scale, Business and Enterprise customers.
</Info>

## Overview

For teams that want to collaborate in ElevenLabs, we offer shared multi seat workspaces. Workspaces offer the following benefits:

* **Shared billing** - Rather than having each of your team members individually create & manage subscriptions, all of your team's character usage and billing is centralized under one workspace.
* **Shared resources** - Within a workspace, your team can share: voices, Agents, Studio projects, dubs, and more.
* **Access management** - Your workspace admin can easily add and remove team members.
* **API Key management** - You can issue and revoke unlimited API keys for your team.
* **Multiple workspace membership** - Users can be members of multiple workspaces and easily switch between them from their account menu.

## Multiple workspace membership

Users can now accept invitations to multiple workspaces, allowing you to collaborate across different teams and organizations.

### Key features

* **Accept invites to other workspaces** - When you accept an invitation to join another workspace, your existing resources (voices, projects, agents, etc.) remain in your original workspace.

* **Copy resources between workspaces** - Workspace owners can copy the following resources from one workspace to another:

  * Voices
  * Studio projects
  * Dubs
  * Basic Agent Configs (note: secrets associated with the agent will not be copied over)

  <Info>
    This feature is disabled by default for Enterprise workspaces. If you want to enable this
    feature, reach out to Support for assistance.
  </Info>

* **Switch between workspaces** - Use the workspace switcher in your account menu to quickly navigate between your workspaces.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c85e9460b00a07fb6c09c22cb068dc12c60392ee4da139d985ce32e4577a2a2f/assets/images/product-guides/administration/workspaces-switch.webp" alt="Switching between workspaces" />

### Workspace limits

* Each user can have only one free workspace at a time
* There is no limit on the number of paid workspaces you can be a member of

## FAQ

<AccordionGroup>
  <Accordion title="How do I create a workspace?">
    ### Creating a workspace

    Multi seat workspaces are automatically enabled on all accounts with Scale, Business and Enterprise subscriptions. On the Scale and Business plans, the account owner will be the workspace admin by default. They will have the power to add more team members as well as nominate others to be an admin. When setting up your Enterprise account, you'll be asked to nominate a workspace admin.
  </Accordion>

  <Accordion title="How do I add a team member to a workspace?">
    ### Adding a team member to a workspace

    <Info>
      Only administrators can add and remove team members.
    </Info>

    <Frame>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5663221cd2bff5a1cd150bdd0a5bdb731ab1c6ee2b82958e4c8c85f33092318b/assets/images/product-guides/workspaces/workspace-product-feature.png" alt="Workspace domain verification" />
    </Frame>

    Once you are logged in, select your profile icon in the top right corner of the dashboard, choose **Workspace settings**, then navigate to the **Members** tab. From there you'll be able to add team members, assign roles and remove members from the workspace.

    #### Bulk Invites

    Enterprise customers can invite their users in bulk once their domain has been verified following the [Verify Domain step](/docs/overview/administration/workspaces/sso#verify-your-email-domain) from the SSO configuration process.

    #### User Auto Provisioning

    Enterprise customers can enable user auto provisioning via the **Security & SSO** tab in workspace settings. When this is enabled, new users with an email domain matching one of your verified domains will automatically join your workspace and take up a seat.
  </Accordion>

  <Accordion title="What roles can I assign members?">
    ### Roles

    There are two roles, Admins and Members. Members have full access to your workspace and can generate an unlimited number of characters (within your current overall plan's limit).

    Admins have all of the access of Members, with the added ability to add/remove teammates and permissions to manage your subscription.
  </Accordion>

  <Accordion title="How do I manage billing?">
    ### Managing Billing

    <Info>
      Only admins can manage billing.
    </Info>

    To manage your billing, select your profile icon in the top right corner of the dashboard and choose **Subscription**. From there, you'll be able to update your payment information and access past invoices.
  </Accordion>

  <Accordion title="How do I manage Service Accounts / API keys?">
    ### Managing Service Accounts

    To manage Service Accounts, select your profile icon in the top right corner of the dashboard and choose **Workspace settings**. Navigate to the **Service Accounts** tab and you'll be able to create / delete service accounts as well as issue new API keys for those service accounts.

    <Note>
      "Workspace API keys" were formerly a type of Service Account with a single API key.
    </Note>
  </Accordion>

  <Accordion title="Who is the workspace owner?">
    ### Managing the workspace owner

    Each workspace can have one owner. By default, this will be the account owner for Scale and Business subscriptions. Ownership can be transferred to another account.

    If you downgrade your subscription and exceed the available number of seats on your new plan, all users apart from the owner will be locked out. The workspace admin can also lock users in advance of the downgrade.
  </Accordion>
</AccordionGroup>


# Billing groups

> Set usage limits for specific groups within your workspace to control costs and manage consumption.

<Info>
  Billing groups are only available to workspace admins and allow you to set usage limits for
  specific groups of users and service accounts within your workspace.
</Info>

## Overview

Billing groups enable workspace admins to set usage limits for specific groups of users and service accounts within a workspace. This feature helps organizations control costs and manage consumption by allocating specific credit quotas to different teams or departments.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/94471dc9c9c7f01268df811d5837f6a76fe401a8fefc215ccf9035b3d6c5d71e/assets/images/product-guides/administration/create-group.webp" alt="Create billing group interface" />
</Frame>

With billing groups, you can:

* **Set usage limits** – Define credit quotas for specific groups of users and service accounts.
* **Control costs** – Prevent overspending by limiting usage for specific teams.
* **Track consumption** – Monitor usage patterns across different groups in your workspace.
* **Manage access** – Automatically restrict requests when a group reaches its limit.

## How it works

Billing groups create a usage limit for a subset of users and service accounts within your workspace. Once configured, all usage by members of a billing group counts toward that group's allocated limit.

* **Single group membership** – Each user or service account can only be in one billing group at a time.
* **Aggregated usage** – All usage by a user or service account counts toward their billing group's limit.
* **Automatic enforcement** – After hitting the usage limit, requests from any member of the group are rejected until the next subscription cycle reset.
* **Subscription cycle reset** – Limits reset at the beginning of each billing cycle, aligned with your workspace's subscription.

## Create and manage billing groups

Workspace admins can create and manage billing groups from **Workspace settings > Groups**.

### Create a new billing group

<Steps>
  #### Create a new group

  Click on **Create New Group** and enter a name for the group.

  ### Set usage limit

  Enter the usage limit for this group. This limit will apply to the combined usage of all members. You can also choose to track usage for the group without setting a limit.

  ### Add members

  Select users and service accounts from your workspace to add to the billing group. Remember that each user and service account can only be in one billing group at a time.
</Steps>

### Adjust limits

Workspace admins can modify the usage limit for a billing group at any time. Changes take effect immediately, but the limit will still reset at the next subscription cycle.

When a billing group reaches its usage limit:

1. All requests made by any member of the group are rejected.
2. Users receive an error indicating the group has exceeded its quota.
3. The restriction remains in place until the next subscription cycle reset.
4. Other billing groups and unassigned users are not affected.
5. Workspace admins can update the usage limit for the group from **Workspace settings > Groups > Manage Usage Limit**.

### Track usage

Workspace admins can monitor and adjust billing group usage from **Workspace settings > Groups**. Click the dollar button to view current usage for each group, and to update usage limits.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9aeadadd05234b03a56cc767fb9a53fffc8ef84ceff814161da8baa99d6ba1bb/assets/images/product-guides/administration/view-usage.webp" alt="View usage across billing groups" />
</Frame>

Individual users can view their own usage details from their account **Settings > Usage & Credit Ceilings**.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e37f90d763fa71cf5b76724f42213eee23ef45cebd8e97d12f35bf1791c5edc8/assets/images/product-guides/administration/personal-usage.webp" alt="View personal usage in account settings" />
</Frame>

### Manage billing group members

Workspace admins can manage groups for individual workspace members from **Workspace settings > Members**. Click the dollar button to view which group the member is part of. If they are not part of a billing group, this button will appear yellow - click it to allocate the user to an existing billing group.

You can also add or remove members from a billing group from **Workspace settings > Groups > Manage Group**.

When a user or service account is added to a billing group, their usage from that point forward starts counting toward that group's limit. Previous usage is not retroactively applied to the billing group. When removed, their future usage will count toward the workspace's overall quota or another billing group if reassigned.

<Warning>
  Once a billing group reaches its limit, all members are blocked from making requests until the
  next billing cycle unless the limit is increased by a workspace admin.
</Warning>


# Service Accounts and API Keys

> An overview on how to configure Service Accounts and API keys for your workspace

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/85b1646b900085c39df273c7337c7428e92325cb621da63c2f6c6d76d2119efd/assets/images/product-guides/workspaces/workspace-service-accounts.png" alt="Service Accounts" />

## Overview

<Info>
  Service Accounts are currently only available for multi-seat customers, and only Workspace admins
  can use this feature. To upgrade, [get in touch with our sales
  team](https://elevenlabs.io/contact-sales).
</Info>

Service Accounts and their respective API keys allow access to workspace resources without relying on an individual's access to ElevenLabs.

## Service Accounts

A service account acts as a workspace member. When originally created, they do not have access to any resources.

The service account can be granted access to resources by either adding the service account to a group or directly sharing resources with the service account.
It is recommended to add them to a group so that future users can be added to the same group and have the same permissions.

## Rotating API keys

<Info>
  When creating a new API key to replace one that you are rotating out, make sure to create the API
  key for the same service account and copy the API key permissions from the old API key to ensure
  that no access is lost.
</Info>

API keys can either be rotated via the UI or via the API.

To rotate API keys on the web, click on your profile icon located in the top right corner of the dashboard, select **Workspace settings**, and then navigate to the **Service Accounts** tab.
From there, you can create a new API key for the same service account. Once you've switched to using the new API key, you can delete the old one from this tab.

To rotate API keys via the API, please see the API reference underneath **Service Accounts** for the relevant endpoints.


# Single Sign-On (SSO)

> An overview on how to set up SSO for your Workspace.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e1575b62be17ed4dbd459539161c7853f9f3e000c8d2eeba01f40e1335d7dad0/assets/images/product-guides/workspaces/workspace-sso.png" alt="SSO" />

## Overview

<Info>
  SSO is currently only available for Enterprise customers, and only Workspace admins can use this
  feature. To upgrade, [get in touch with our sales team](https://elevenlabs.io/contact-sales).
</Info>

Single Sign-On (SSO) allows your team to log in to ElevenLabs by using your existing identity provider. This allows your team to use the same credentials they use for other services to log in to ElevenLabs.

## Guide

<Steps>
  <Step title="Access your SSO settings">
    Click on your profile icon located in the top right corner of the dashboard, select **Workspace settings**, and then navigate to the **Security & SSO** tab.
  </Step>

  <Step title="Choose identity providers">
    You can choose from a variety of pre-configured identity providers, including Google, Apple, GitHub, etc. Custom organization SSO providers will only appear in this list after they have been configured, as shown in the "SSO Provider" section.
  </Step>

  <Step title="Verify your email domain">
    Next, you need to verify your email domain for authentication. This lets ElevenLabs know that you own the domain you are configuring for SSO. This is a security measure to prevent unauthorized access to your Workspace.

    Click the **Verify domain** button and enter the domain name you want to verify. After completing this step, click on the domain pending verification. You will be prompted to add a DNS TXT record to your domain's DNS settings. Once the DNS record has been added, click on the **Verify** button.
  </Step>

  <Step title="Configure SSO">
    If you want to configure your own SSO provider, select the SSO provider dropdown to select between OIDC (OpenID Connect) and SAML (Security Assertion Markup Language).

    <Info>
      Only Service Provider (SP) initiated SSO is supported for SAML. To ease the sign in process, you can create a bookmark app in your SSO provider linking to 

      [https://elevenlabs.io/app/sign-in?use_sso=true](https://elevenlabs.io/app/sign-in?use_sso=true)

      . You can include the user's email as an additional query parameter to pre-fill the field. For example 

      [https://elevenlabs.io/app/sign-in?use_sso=true&email=test@test.com](https://elevenlabs.io/app/sign-in?use_sso=true&email=test@test.com)
    </Info>

    Once you've filled out the required fields, click the **Update SSO** button to save your changes.

    <Warning>
      Configuring a new SSO provider will log out all Workspace members currently logged in with SSO.
    </Warning>
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Microsoft Entra Identifier / Azure AD - SAML">
    **What to fill in on the Entra / Azure side**:

    * **Identifier (Entity ID)**: Use the *Service Provider Entity ID* value from the ElevenLabs SSO configuration page.
    * **Reply URL (Assertion Consumer Service URL)**: Use `https://elevenlabs.io/__/auth/handler`
      * For EU residency, use `https://eu.elevenlabs.io/__/auth/handler`
      * For India residency, use `https://in.elevenlabs.io/__/auth/handler`
    * **ACS URL**: Same as the Reply URL above.

    **What to fill in on the ElevenLabs side**:

    * **IdP Entity ID**: Use the *Microsoft Entra Identifier* (the full URL, e.g., `https://sts.windows.net/{tenant-id}/`)
    * **IdP Sign-In URL**: Use the *Login URL* from Entra / Azure
  </Accordion>

  <Accordion title="Okta - SAML">
    **What to fill in on the Okta side**:

    * **Audience Restriction**: Use the *Service Provider Entity ID* from the ElevenLabs SSO configuration page.
    * **Single Sign-On URL/Recipient URL/Destination**: Use `https://elevenlabs.io/__/auth/handler`
      * For EU residency, use `https://eu.elevenlabs.io/__/auth/handler`
      * For India residency, use `https://in.elevenlabs.io/__/auth/handler`

    **What to fill in on the ElevenLabs side**:

    * Create the application in Okta and then fill out these fields using the results
    * **Identity Provider Entity Id**: Use the SAML Issuer ID
    * **Identity Provider Sign-In URL**: Use the Sign On URL from Okta
      * This can generally be found in the Metadata details within the Sign On tab of the Okta application
      * It will end in **/sso/saml**
  </Accordion>

  <Accordion title="OneLogin - SAML">
    **What to fill in on the OneLogin side**:

    * **Recipient**: Use `https://elevenlabs.io/__/auth/handler`
      * For EU residency, use `https://eu.elevenlabs.io/__/auth/handler`
      * For India residency, use `https://in.elevenlabs.io/__/auth/handler`
  </Accordion>

  <Accordion title="OIDC - Common Errors">
    Please ensure that `email` and `email_verified` are included in the custom attributes returned in the OIDC response. Without these, the following errors may be hit:

    * *No email address was received*: Fixed by adding **email** to the response.
    * *Account exists with different credentials*: Fixed by adding **email\_verified** to the response
  </Accordion>

  <Accordion title="I am getting the error 'Unable to login with saml.workspace...'">
    * One known error: Inside the `<saml:Subject>` field of the SAML response, make sure `<saml:NameID>` is set to the email address of the user.
  </Accordion>
</AccordionGroup>


# Sharing resources

> An overview on how to share resources within a Workspace.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1d1fe7f982282bb04bf6f27a363e384a83f7cf25725bef4a47a536d7e8f5f70e/assets/images/product-guides/workspaces/share-project.png" alt="Sharing a project" />

## Overview

If your subscription plan includes multiple seats, you can share resources with your members. Resources you
can share include: voices, ElevenLabs agents, studio projects and more. Check the
[Workspaces API](/docs/api-reference/workspace/resources/share) for an up-to-date list of resources you can share.

## Sharing

You can share a **resource** with a **principal**. A principal is one of the following:

* A user
* A user group
* A service account

A resource can be shared with at most 100 principals.

Service Accounts behave like individual users. They don't have access to anything in the Workspace when they are created, but they can be added to resources by resource admins.

#### Default Sharing

If you would like to share with specific principals for each new resource by default, this can be enabled in your personal settings page under **Default Sharing Preferences**.
Every new resource created after this is enabled will be automatically shared with the principals that you add here.

## Roles

When you share a resource with a principal, you can assign them a **role**. We support the following roles:

* **Viewer**: Viewers can discover the resource and its contents. They can also "use" the resource, e.g., generate TTS with a voice or listen to the audio of a studio instance.
* **Editor**: Everything a viewer can do, plus they can also edit the contents of the resource.
* **Admin**: Everything an editor can do, plus they can also delete the resource and manage sharing permissions.

When you create a resource, you have admin permissions on it. Other resource admins cannot remove your admin permissions on the resources you created.

<Warning>
  Workspace admins have admin permissions on all resources in the workspace. This can be removed
  from them only by removing their Workspace admin role.
</Warning>


# User groups

> An overview on how to create and manage user groups.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b3352775553098f965b4c3a92526bf71c6afb836ce32b6eccac2947b80d0fd01/assets/images/product-guides/workspaces/manage-group.png" alt="Group Management" />

## Overview

<Info>
   Only Workspace admins can create, edit, and delete user groups. 
</Info>

User groups allow you to manage permissions for multiple users at once.

## Creating a user group

You can create a user group from **Workspace settings**. You can then [share resources](/docs/overview/administration/workspaces/sharing-resources) with the group directly.
If access to a user group is lost, access to resources shared with that group is also lost.

## Multiple groups

User groups cannot be nested, but you can add users to multiple groups. If a user is part of multiple groups, they will have the union of all the permissions of the groups they are part of.

For example, you can create a voice and grant the **Sales** and **Marketing** groups viewer and editor roles on the voice, respectively.
If a user is part of both groups, they will have editor permissions on the voice. Losing access to the **Marketing** group will downgrade the user's permissions to viewer.

## Disabling platform features

Permissions for groups can be revoked for specific product features, such as Professional Voice Cloning or Sound Effects.
To do this, you first have to remove the relevant permissions from the **Everyone** group. Afterwards, enable the permissions for each group that should have access.


# Webhooks

> Enable external integrations by receiving webhook events.

## Overview

Certain events within ElevenLabs can be configured to trigger webhooks, allowing external applications and systems to receive and process these events as they occur. Currently supported event types include:

| Event type                       | Description                                                  |
| -------------------------------- | ------------------------------------------------------------ |
| `post_call_transcription`        | A Agents Platform call has finished and analysis is complete |
| `voice_removal_notice`           | A shared voice is scheduled to be removed                    |
| `voice_removal_notice_withdrawn` | A shared voice is no longer scheduled for removal            |
| `voice_removed`                  | A shared voice has been removed and is no longer useable     |

## Configuration

Webhooks can be created, disabled and deleted from the general settings page. For users within [Workspaces](/docs/overview/administration/workspaces/overview), only the workspace admins can configure the webhooks for the workspace.

<Frame background="subtle">
  ![HMAC webhook configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9ea298daac1c64eb43c802a12f7824e83accca44ba2edd1d01a39bcd62c0b9d6/assets/images/product-guides/administration/hmacwebhook.png)
</Frame>

After creation, the webhook can be selected to listen for events within product settings such as [Agents Platform](/docs/agents-platform/workflows/post-call-webhooks).

Webhooks can be disabled from the general settings page at any time. Webhooks that repeatedly fail are auto disabled if there are 10 or more consecutive failures and the last successful delivery was more than 7 days ago or has never been successfully delivered. Auto-disabled webhooks require re-enabling from the settings page. Webhooks can be deleted if not in use by any products.

## Integration

To integrate with webhooks, the listener should create an endpoint handler to receive the webhook event data POST requests. After validating the signature, the handler should quickly return HTTP 200 to indicate successful receipt of the webhook event, repeat failure to correctly return may result in the webhook becoming automatically disabled.
Each webhook event is dispatched only once, refer to the [API](/docs/api-reference/introduction) for methods to poll and get product specific data.

### Top-level fields

| Field             | Type   | Description              |
| ----------------- | ------ | ------------------------ |
| `type`            | string | Type of event            |
| `data`            | object | Data for the event       |
| `event_timestamp` | string | When this event occurred |

## Example webhook payload

```json
{
  "type": "post_call_transcription",
  "event_timestamp": 1739537297,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "status": "done",
    "transcript": [
      {
        "role": "agent",
        "message": "Hey there angelo. How are you?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 0,
        "conversation_turn_metrics": null
      },
      {
        "role": "user",
        "message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 2,
        "conversation_turn_metrics": null
      },
      {
        "role": "agent",
        "message": "I do not have access to fun facts about Eleven Labs. However, I can share some general information about the company. Eleven Labs is an AI voice technology platform that specializes in voice cloning and text-to-speech...",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 9,
        "conversation_turn_metrics": {
          "convai_llm_service_ttfb": {
            "elapsed_time": 0.3704247010173276
          },
          "convai_llm_service_ttf_sentence": {
            "elapsed_time": 0.5551181449554861
          }
        }
      }
    ],
    "metadata": {
      "start_time_unix_secs": 1739537297,
      "call_duration_secs": 22,
      "cost": 296,
      "deletion_settings": {
        "deletion_time_unix_secs": 1802609320,
        "deleted_logs_at_time_unix_secs": null,
        "deleted_audio_at_time_unix_secs": null,
        "deleted_transcript_at_time_unix_secs": null,
        "delete_transcript_and_pii": true,
        "delete_audio": true
      },
      "feedback": {
        "overall_score": null,
        "likes": 0,
        "dislikes": 0
      },
      "authorization_method": "authorization_header",
      "charging": {
        "dev_discount": true
      },
      "termination_reason": ""
    },
    "analysis": {
      "evaluation_criteria_results": {},
      "data_collection_results": {},
      "call_successful": "success",
      "transcript_summary": "The conversation begins with the agent asking how Angelo is, but Angelo redirects the conversation by requesting a fun fact about 11 Labs. The agent acknowledges they don't have specific fun facts about Eleven Labs but offers to provide general information about the company. They briefly describe Eleven Labs as an AI voice technology platform specializing in voice cloning and text-to-speech technology. The conversation is brief and informational, with the agent adapting to the user's request despite not having the exact information asked for."
    },
    "conversation_initiation_client_data": {
      "conversation_config_override": {
        "agent": {
          "prompt": null,
          "first_message": null,
          "language": "en"
        },
        "tts": {
          "voice_id": null
        }
      },
      "custom_llm_extra_body": {},
      "dynamic_variables": {
        "user_name": "angelo"
      }
    }
  }
}
```

## Authentication

It is important for the listener to validate all incoming webhooks. Webhooks currently support authentication via HMAC signatures. Set up HMAC authentication by:

* Securely storing the shared secret generated upon creation of the webhook
* Verifying the ElevenLabs-Signature header in your endpoint using the SDK

The ElevenLabs SDK provides a `constructEvent` method that handles signature verification, timestamp validation, and payload parsing.

<Tabs>
  <Tab title="Python">
    Example webhook handler using FastAPI:

    ```python
    from dotenv import load_dotenv
    from fastapi import FastAPI, Request
    from fastapi.responses import JSONResponse
    from elevenlabs.client import ElevenLabs
    import os

    load_dotenv()

    app = FastAPI()
    elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
    )

    WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")

    @app.post("/webhook")
    async def receive_message(request: Request):
        payload = await request.body()
        signature = request.headers.get("elevenlabs-signature")

        try:
            event = elevenlabs.webhooks.construct_event(
                payload=payload.decode("utf-8"),
                signature=signature,
                secret=WEBHOOK_SECRET,
            )
        except Exception as e:
            return JSONResponse(content={"error": "Invalid signature"}, status_code=401)

        # Process the webhook event
        if event.type == "post_call_transcription":
            print(f"Received transcription: {event.data}")

        return {"status": "received"}
    ```
  </Tab>

  <Tab title="JavaScript">
    <Tabs>
      <Tab title="Express">
        Example webhook handler using Express:

        ```javascript
        import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
        import express from 'express';

        const app = express();

        const elevenlabs = new ElevenLabsClient();
        const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

        // Use express.text() to preserve raw body for signature verification
        app.post('/webhook', express.text({ type: 'application/json' }), async (req, res) => {
          const signature = req.headers['elevenlabs-signature'];
          const payload = req.body; // Raw string body

          let event;
          try {
            event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
          } catch (error) {
            return res.status(401).json({ error: 'Invalid signature' });
          }

          // Process the webhook event
          if (event.type === 'post_call_transcription') {
            console.log('Received transcription:', event.data);
          }

          res.status(200).json({ received: true });
        });
        ```
      </Tab>

      <Tab title="Next.js">
        Example webhook handler using Next.js API route:

        ```typescript app/api/webhook/route.ts
        import { NextResponse } from 'next/server';
        import type { NextRequest } from 'next/server';
        import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

        const elevenlabs = new ElevenLabsClient();
        const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

        export async function POST(req: NextRequest) {
          const body = await req.text();
          const signature = req.headers.get('elevenlabs-signature');

          let event;
          try {
            event = await elevenlabs.webhooks.constructEvent(body, signature, WEBHOOK_SECRET);
          } catch (error) {
            return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
          }

          // Process the webhook event
          if (event.type === 'post_call_transcription') {
            console.log('Received transcription:', event.data);
          }

          return NextResponse.json({ received: true }, { status: 200 });
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# ElevenCreative

> Create studio-quality AI audio for any use case

<iframe width="100%" height="400" src="https://www.youtube.com/embed/q6XE5cjXZ-A" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

The ElevenCreative platform transforms text into lifelike audio across 50+ languages with the most advanced voice AI models available. From audiobooks to ads, podcasts to games, create professional voice content at scale with intuitive tools for creators, producers, and developers.

<div id="agents-cards">
  <a href="/docs/creative-platform/playground/text-to-speech">
    <div>
      <svg fill="none" stroke="currentColor" strokeWidth="1.5" viewBox="0 0 24 24">
        <path strokeLinecap="round" strokeLinejoin="round" d="M19.114 5.636a9 9 0 010 12.728M16.463 8.288a5.25 5.25 0 010 7.424M6.75 8.25l4.72-4.72a.75.75 0 011.28.53v15.88a.75.75 0 01-1.28.53l-4.72-4.72H4.51c-.88 0-1.704-.507-1.938-1.354A9.01 9.01 0 012.25 12c0-.83.112-1.633.322-2.396C2.806 8.756 3.63 8.25 4.51 8.25H6.75z" />
      </svg>
    </div>

    <div>
      <h3>
        Playground
      </h3>

      <p>
        Test and experiment with text-to-speech, voice changing, and sound effects in real-time
      </p>
    </div>
  </a>

  <a href="/docs/creative-platform/products/studio">
    <div>
      <svg fill="none" stroke="currentColor" strokeWidth="1.5" viewBox="0 0 24 24">
        <path strokeLinecap="round" strokeLinejoin="round" d="M9.53 16.122a3 3 0 00-5.78 1.128 2.25 2.25 0 01-2.4 2.245 4.5 4.5 0 008.4-2.245c0-.399-.078-.78-.22-1.128zm0 0a15.998 15.998 0 003.388-1.62m-5.043-.025a15.994 15.994 0 011.622-3.395m3.42 3.42a15.995 15.995 0 004.764-4.648l3.876-5.814a1.151 1.151 0 00-1.597-1.597L14.146 6.32a15.996 15.996 0 00-4.649 4.763m3.42 3.42a6.776 6.776 0 00-3.42-3.42" />
      </svg>
    </div>

    <div>
      <h3>
        Products
      </h3>

      <p>
        Purpose-built tools that integrate multiple capabilities into streamlined workflows for
        specific use cases like long-form content, video localization, and music production
      </p>
    </div>
  </a>

  <a href="/docs/creative-platform/voices/voice-library">
    <div>
      <svg fill="none" stroke="currentColor" strokeWidth="1.5" viewBox="0 0 24 24">
        <path strokeLinecap="round" strokeLinejoin="round" d="M15.75 6a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0zM4.501 20.118a7.5 7.5 0 0114.998 0A17.933 17.933 0 0112 21.75c-2.676 0-5.216-.584-7.499-1.632z" />
      </svg>
    </div>

    <div>
      <h3>
        Voices
      </h3>

      <p>
        Access 5,000+ pre-made voices or clone your own with instant or professional voice cloning
      </p>
    </div>
  </a>
</div>

## Platform capabilities

ElevenLabs capabilities span synthesis, dubbing, music, sound design, voices, and analytics. Review
the [capabilities overview](/docs/overview/intro#capabilities) for detailed breakdowns, parameters, and
best-fit guidance across every use case.

## Use cases

The ElevenCreative platform powers audio production across industries:

* **Audiobooks & Publishing** - Produce full-length audiobooks with consistent character voices
* **Content Creation** - Generate voiceovers for YouTube, podcasts, and social media
* **Gaming** - Create dynamic character voices and sound effects
* **Film & TV** - Localize content with AI dubbing in 30+ languages
* **Advertising** - Scale ad campaigns globally with multilingual voice AI
* **Education** - Produce engaging e-learning content with natural narration


# ElevenCreative quickstart

> Start creating studio-quality AI audio in minutes

Welcome to the ElevenCreative platform. This guide will help you get started with creating AI-generated audio for your projects.

<Steps>
  ### Sign up for an account

  Create your free [ElevenLabs account](https://elevenlabs.io/app/sign-up) to get started. Free tier includes:

  * 10,000 characters per month
  * Access to 3,000+ voices in our Voice Library
  * Text to Speech, Voice Changer, Sound Effects, [and many more](/docs/overview/capabilities/text-to-speech)
  * Access to the Playground for experimentation

  ### Choose your voice

  Browse our [Voice Library](https://elevenlabs.io/app/voice-library) to find the perfect voice for your project. You can:

  <Warning>
    The voice library is not available via the API to free tier users.
  </Warning>

  * Search by language, accent, age, and use case
  * Preview voices by clicking the orb next to the voice name for a short preview
  * Clone your own voice with [Instant Voice Cloning](/docs/creative-platform/voices/voice-cloning/instant-voice-cloning)
  * Create custom voices with [Voice Design](/docs/creative-platform/voices/voice-design)

  For more information on voice cloning best practices, see our [voice cloning guide](/docs/creative-platform/voices/voice-cloning).

  ### Select your model

  Choose the model that fits your use case:

  * **Multilingual v2** - Most stable model with support for 32 languages
  * **Eleven v3** - Most emotional model with advanced expressiveness
  * **Flash v2.5** - Ultra-low latency for real-time applications

  Learn more about our [models](/docs/overview/models).

  ### Generate your first audio

  Head to the [Text to Speech playground](https://elevenlabs.io/app/speech-synthesis/text-to-speech) to generate your first audio:

  1. Select a voice from the dropdown
  2. Enter your text (up to 5,000 characters)
  3. Adjust voice settings if needed
  4. Click "Generate" to create your audio
  5. Download or share your generated audio

  ### Explore more features

  Once you're comfortable with basic text-to-speech:

  * [Voice Changer](/docs/creative-platform/playground/voice-changer) - Transform your voice in real-time
  * [Sound Effects](/docs/creative-platform/playground/sound-effects) - Generate custom audio effects
  * [Studio](/docs/creative-platform/products/studio) - Create long-form content with advanced editing
  * [Dubbing](/docs/creative-platform/products/dubbing) - Translate videos into 30+ languages
  * [Playground](/docs/creative-platform/playground/text-to-speech) - Experiment with all features
  * [Products](/docs/creative-platform/products/studio) - Explore our full product suite
  * [Voices](/docs/creative-platform/voices/voice-library) - Discover and manage voices
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Playground" icon="flask" href="/docs/creative-platform/playground/text-to-speech">
    Experiment with text-to-speech, voice changing, and sound effects
  </Card>

  {' '}

  <Card title="Studio" icon="wand-magic-sparkles" href="/docs/creative-platform/products/studio">
    Create professional audiobooks, podcasts, and narration
  </Card>

  {' '}

  <Card title="Voice Cloning" icon="clone" href="/docs/creative-platform/voices/voice-library">
    Clone your voice or create custom voices
  </Card>

  <Card title="API Integration" icon="code" href="/docs/developers/quickstart">
    Integrate ElevenLabs into your applications
  </Card>
</CardGroup>

## Common questions

<AccordionGroup>
  <Accordion title="What can I create with ElevenCreative?">
    ElevenCreative enables you to create a wide range of audio and visual content:

    * **Audio**: Audiobooks, podcasts, video voiceovers, game audio, ads, e-learning content, music, sound effects, and voice transformations
    * **Video & Images**: Generate and enhance images and videos from text prompts, upscale existing visuals up to 4x resolution, and add realistic lip-sync with audio
    * **Dubbing**: Translate audio and video content into 32 languages while preserving speaker emotion, timing, and tone
    * **Templates**: Combine multiple capabilities in packaged templates like Studio for long-form content, Dubbing Studio for video translation, and more

    The platform supports 50+ languages and offers thousands of voices to choose from.
  </Accordion>

  {' '}

  <Accordion title="Do I need coding skills to use ElevenCreative?">
    No. ElevenCreative is designed for creators of all skill levels. Use our visual tools and
    playground to create audio without any coding. If you're a developer, check out our [API
    documentation](/docs/developers/quickstart).
  </Accordion>

  {' '}

  <Accordion title="Can I use my generated audio commercially?">
    Yes, with a paid plan. Free tier is limited to personal, non-commercial use. See our [pricing
    page](https://elevenlabs.io/pricing) for plan details and our [terms of
    service](https://elevenlabs.io/terms-of-use) to ensure you comply with all usage requirements.
  </Accordion>
</AccordionGroup>


# Text to Speech

> A guide on how to turn text to speech with ElevenLabs

<iframe width="100%" height="400" src="https://www.youtube.com/embed/HSJLQFzgNYo" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

ElevenLabs' Text to Speech technology is integral to our offerings, powering high-quality AI-generated speech across various applications worldwide. It's likely you've already encountered our voices in action, delivering lifelike audio experiences.

To get started generating your first audio using Text to Speech, it's very simple. However, to get the most out of this feature, there are a few things you need to keep in mind.

## Guide

<Frame background="subtle">
  ![Text to Speech demo](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/32b6abef4b76c8652b0e55dbb26c9694fdc82e191a062678b93c9a5ca5d80c94/assets/images/product-guides/text-to-speech/text-to-speech-demo.png)
</Frame>

<Steps title="Adjust settings (optional)" toc={false}>
  <Step title="Text input">
    Type or paste your text into the input box on the Text to Speech page.
  </Step>

  <Step title="Voice selection">
    Select the voice you wish to use from your Voices at the bottom left of the screen.
  </Step>

  <Step title="Adjust settings (optional)">
    Modify the voice settings for the desired output.
  </Step>

  <Step title="Generate">
    Click the 'Generate' button to create your audio file.
  </Step>
</Steps>

## Settings

Get familiar with the voices, models & settings for creating high-quality speech.

The settings you use, especially the voice and the model, significantly impact the output. It's quite important to get familiar with these and understand some best practices. While other settings also influence the output, their impact is less significant compared to the voice and model you select.

The order of importance goes as follows: **Voice** selection is most important, followed by **Model** selection, and then model **Settings**. All of these, and their combination, will influence the output.

<AccordionGroup>
  <Accordion title="Voices">
    ### Voices

    <Frame background="subtle">
      ![Text to Speech voice
      selection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a1a2f62118fa246f300c666a5a4f3fbd18cc9bfed023a8c6a010782545da1254/assets/images/product-guides/text-to-speech/text-to-speech-voices.png)
    </Frame>

    We offer many types of voices, including the curated **Default Voices**, our vast **Voices Library&#x20;**&#x77;ith almost any voices you can imagine, completely synthetic voices created using our **Voice Design** tool, and you can create your own collection of cloned voices using our two technologies: **Instant Voice Cloning** and **Professional Voice Cloning**.

    Not all voices are equal, and much depends on the source audio used to create them. Some voices will provide a better, more human performance and delivery, while others will be more stable.

    **Choosing the right voice for your specific content is crucial.** This is most likely the most significant decision that will have the most significant impact on the final output. It determines the gender, tone, accent, cadence, and delivery. It's worth spending extra time to select the perfect voice and properly test it to ensure it is consistent and meets your expectations.

    For generating speech in a specific language, using a native voice from the Voice Library or cloning a voice speaking that language with the correct accent will yield the best results. While any voice can technically speak any language, it will retain its original accent. For example, using a native English voice to generate French speech will likely result in the output being in French but with an English accent, as the AI must generalize how that voice would sound in a language it wasn't trained on.

    [Learn more about voices](/docs/overview/capabilities/voices)

    If you have a voice that you like but want a different delivery, our [Voice Remixing](/docs/overview/capabilities/voice-remixing) tool can help. It lets you use natural language prompts to change a voice's delivery, cadence, tone, gender, and even accents. When changing accents, the base voice and target accent are very important. Results can vary; sometimes it works perfectly, while other times it might take a few tries to get it right.

    You can get some really good results with Voice Remixing, but they will not usually be as good as a properly cloned Professional Voice Clone. They will be closer to that of an Instant Voice Clone.

    Keep in mind, voice remixing only works for specific voices. For example, you can't remix voices from the Voice Library; you can only remix voices that you have created yourself or the default voices.
  </Accordion>

  <Accordion title="Models">
    ### Models

    <Frame background="subtle">
      ![Text to Speech model
      selection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/aa32e23cc2a196a48ff47650249e612e7e5da023fd2f69244f27c5fea7968b75/assets/images/product-guides/text-to-speech/text-to-speech-models.png)
    </Frame>

    We offer two families of models: **Standard (high-quality)** models and **Flash** models, which are optimized for extremely low latency. Most families include both English-only and multilingual versions.

    *The Eleven v3 model currently only comes in one version: the standard multilingual version.*

    Model selection is the second most significant influence on your final audio output, right after voice selection. We recommend taking a moment to test the different models with your chosen voice to find the best fit. All of our models have strengths and weaknesses and work better with some voices than others, so finding a good pairing is important.

    If your output will be exclusively in English, we strongly recommend using one of our English-only models. They are often easier to work with, more stable, and generally offer superior performance for English-only content. If your content will be in another language or potentially multilingual, you must use one of the multilingual models.

    <CardGroup cols={2} rows={2}>
      <Card title="Eleven v3" href="/docs/overview/models#eleven-v3">
        Our most emotionally rich, expressive speech synthesis model

        <div>
          <div>
            Dramatic delivery and performance
          </div>

          <div>
            70+ languages supported
          </div>

          <div>
            5,000 character limit
          </div>

          <div>
            Support for natural multi-speaker dialogue
          </div>
        </div>
      </Card>

      <Card title="Eleven Multilingual v2" href="/docs/overview/models#multilingual-v2">
        Lifelike, consistent quality speech synthesis model

        <div>
          <div>
            Natural-sounding output
          </div>

          <div>
            29 languages supported
          </div>

          <div>
            10,000 character limit
          </div>

          <div>
            Most stable on long-form generations
          </div>
        </div>
      </Card>

      <Card title="Eleven Flash v2.5" href="/docs/overview/models#flash-v25">
        Our fast, affordable speech synthesis model

        <div>
          <div>
            Ultra-low latency (~75ms†)
          </div>

          <div>
            32 languages supported
          </div>

          <div>
            40,000 character limit
          </div>

          <div>
            Faster model, 50% lower price per character
          </div>
        </div>
      </Card>

      <Card title="Eleven Turbo v2.5" href="/docs/overview/models#turbo-v25">
        High quality, low-latency model with a good balance of quality and speed

        <div>
          <div>
            High quality voice generation
          </div>

          <div>
            32 languages supported
          </div>

          <div>
            40,000 character limit
          </div>

          <div>
            Low latency (~250ms-300ms†), 50% lower price per character
          </div>
        </div>
      </Card>
    </CardGroup>

    [Learn more about our models](/docs/overview/models)
  </Accordion>

  <Accordion title="Voice settings">
    ### Voice settings

    <Frame background="subtle">
      ![Text to Speech voice
      settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9e08b179bfd640650ca5225b7e2e5b8d9d4c192d63a80d2478e4078e408bf869/assets/images/product-guides/text-to-speech/text-to-speech-settings.webp)
    </Frame>

    The most common setting is stability around 50, similarity around 75, and keeping style at 0, with minimal changes thereafter. Of course, this all depends on the original voice and the style of performance you're aiming for.

    It's important to note that the AI is non-deterministic; setting the sliders to specific values won't guarantee the same results every time. Instead, the sliders function more as a range, determining how wide the randomization can be between each generation.

    #### Speed

    The speed setting allows you to either speed up or slow down the speed of the generated speech. The default value is 1.0, which means that the speed is not adjusted. Values below 1.0 will slow the voice down, to a minimum of 0.7. Values above 1.0 will speed up the voice, to a maximum of 1.2. Extreme values may affect the quality of the generated speech.

    #### Stability

    The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice. As mentioned before, this is also influenced heavily by the original voice. Setting the slider too low may result in odd performances that are overly random and cause the character to speak too quickly. On the other hand, setting it too high can lead to a monotonous voice with limited emotion.

    For a more lively and dramatic performance, it is recommended to set the stability slider lower and generate a few times until you find a performance you like.

    On the other hand, if you want a more serious performance, even bordering on monotone at very high values, it is recommended to set the stability slider higher. Since it is more consistent and stable, you usually don't need to generate as many samples to achieve the desired result. Experiment to find what works best for you!

    #### Similarity

    The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. If the original audio is of poor quality and the similarity slider is set too high, the AI may reproduce artifacts or background noise when trying to mimic the voice if those were present in the original recording.

    #### Style exaggeration

    With the introduction of the newer models, we also added a style exaggeration setting. This setting attempts to amplify the style of the original speaker. It does consume additional computational resources and might increase latency if set to anything other than 0. It's important to note that using this setting has shown to make the model slightly less stable, as it strives to emphasize and imitate the style of the original voice.

    *In general, we recommend keeping this setting at 0 at all times.*

    #### Speaker Boost

    This setting boosts the similarity to the original speaker. However, using this setting requires a slightly higher computational load, which in turn increases latency. The differences introduced by this setting are generally rather subtle.

    <Note>
      Speaker Boost is not available for the Eleven v3 model.
    </Note>
  </Accordion>
</AccordionGroup>

## Generate

Once you have selected your voice, chosen a model, and configured your settings, the generation process is straightforward: you input text, press "**Generate Speech**," and the audio is then generated.

Although the process is very simple on the surface, the text input you provide is extremely important for achieving the desired output. When using words that might be "outside of distribution"—meaning things the AI rarely encountered during training—such as strange names, unusual abbreviations, symbols, or even emojis, you can risk confusing the AI and making the output more unstable. Emojis and certain symbols are particularly difficult for the AI to interpret correctly.

When using Text to Speech via the UI, we run an automated normalization step on your input to improve text legibility and ease processing for the AI. Generally, this step converts symbols and numbers into written-out text, which guides the AI on correct pronunciation.

A best practice we strongly recommend is to avoid writing numbers as digits or using symbols, especially when using multilingual models (though this also applies to English-only models). Since numbers and symbols are written the same across many languages but pronounced differently, relying on digits creates ambiguity for the AI. For example, the number "1" is written identically in English and many other languages but pronounced differently. Writing out the number in text, such as "one," removes the need for the AI to interpret what it is supposed to do.

We are working on more advanced workflows to allow you to influence the AI's delivery and performance using what we call **Audio Tags**. This feature is available in our Eleven v3 model. If you're interested in learning more about this feature, we recommend reading our [Eleven v3 documentation](/docs/overview/capabilities/text-to-speech/best-practices#prompting-eleven-v3).

## FAQ

<AccordionGroup>
  <Accordion title="Good input equals good output">
    The first factor, and one of the most important, is that good, high-quality, and consistent input will result in good, high-quality, and consistent output.

    If you provide the AI with audio that is less than ideal—for example, audio with a lot of noise, reverb on clear speech, multiple speakers, or inconsistency in volume or performance and delivery—the AI will become more unstable, and the output will be more unpredictable.

    If you plan on cloning your own voice, we strongly recommend that you go through our guidelines in the documentation for creating proper voice clones, as this will provide you with the best possible foundation to start from. Even if you intend to use only Instant Voice Clones, it is advisable to read the Professional Voice Cloning section as well. This section contains valuable information about creating voice clones, even though the requirements for these two technologies are slightly different.
  </Accordion>

  <Accordion title="Use the right voice">
    The second factor to consider is that the voice you select will have a tremendous effect on the output. Not only, as mentioned in the first factor, is the quality and consistency of the samples used to create that specific clone extremely important, but also the language and tonality of the voice.

    If you want a voice that sounds happy and cheerful, you should use a voice that has been cloned using happy and cheerful samples. Conversely, if you desire a voice that sounds introspective and brooding, you should select a voice with those characteristics.

    However, it is also crucial to use a voice that has been trained in the correct language. For example, all of the professional voice clones we offer as default voices are English voices and have been trained on English samples. Therefore, if you have them speak other languages, their performance in those languages can be unpredictable. It is essential to use a voice that has been cloned from samples where the voice was speaking the language you want the AI to then speak.
  </Accordion>

  <Accordion title="Use proper formatting">
    This may seem slightly trivial, but it can make a big difference. The AI tries to understand how to read something based on the context of the text itself, which means not only the words used but also how they are put together, how punctuation is applied, the grammar, and the general formatting of the text.

    This can have a small but impactful influence on the AI's delivery. If you were to misspell a word, the AI won't correct it and will try to read it as written.
  </Accordion>

  <Accordion title="Nondeterministic">
    The settings of the AI are nondeterministic, meaning that even with the same initial conditions (voice, settings, model), it will give you slightly different output, similar to how a voice actor will deliver a slightly different performance each time.

    This variability can be due to various factors, such as the options mentioned earlier: voice, settings, model. Generally, the breadth of that variability can be controlled by the stability slider. A lower stability setting means a wider range of variability between generations, but it also introduces inter-generational variability, where the AI can be a bit more performative.

    A wider variability can often be desirable, as setting the stability too high can make certain voices sound monotone as it does give the AI the same leeway to generate more variable content. However, setting the stability too low can also introduce other issues where the generations become unstable, especially with certain voices that might have used less-than-ideal audio for the cloning process.

    The default setting of 50 is generally a great starting point for most applications.
  </Accordion>
</AccordionGroup>


# Voice changer

> A guide on how to transform audio between voices while preserving emotion and delivery.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/d3B3BiCmczc" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Voice changer (previously Speech-to-Speech) allows you to convert one voice (source voice) into another (cloned voice) while preserving the tone and delivery of the original voice.

Voice changer can be used to complement Text-to-Speech (TTS) by fixing pronunciation errors or infusing that special performance you've been wanting to exude. Voice changer is especially useful for emulating those subtle, idiosyncratic characteristics of the voice that give a more emotive and human feel. Some key features include:

* Greater accuracy with whispering
* The ability to create audible sighs, laughs, or cries
* Greatly improved detection of tone and emotion
* Accurately follows the input speaking cadence
* Language/accent retention

<AccordionGroup>
  <Accordion title="Watch a video of voice changer in action">
    <iframe width="100%" height="400" src="https://www.youtube.com/embed/GBdOQClluIA" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />
  </Accordion>
</AccordionGroup>

## Guide

<Frame background="subtle">
  ![Voice changer demo](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2edaef4c56e389edff8faf0c5a43247631432cead38d23023fb6263bb258cc55/assets/images/product-guides/voice-changer/voice-changer-demo.png)
</Frame>

Audio can be uploaded either directly with an audio file, or spoken live through a microphone. The audio file must be less than **50mb in size**, and either the audio file or your live recording cannot exceed **5 minutes in length**.

If you have material longer than 5 minutes, we recommend breaking it up into smaller sections and generating them separately. Additionally, if your file size is too large, you may need to compress/convert it to an mp3.

### Existing audio file

To upload an existing audio file, either click the audio box, or drag and drop your audio file directly onto it.

### Record live

Press the **Record Audio** button in the audio box, and then once you are ready to begin recording, press the **Microphone** button to start. After you're finished recording, press the **Stop** button.

You will then see the audio file of this recording, which you can then playback to listen to - this is helpful to determine if you are happy with your performance/recording. The character cost will be displayed on the bottom-left corner, and you will not be charged this quota for recording anything - only when you press "Generate".

**The cost for a voice changer generation is solely duration-based at 1000 characters per minute.**

## Settings

<Frame background="subtle">
  ![Voice changer settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b1f916391e35ad88e7820ca098831d9b76aa6b95ac3689b51f794b526e8778b3/assets/images/product-guides/voice-changer/voice-changer-settings.png)
</Frame>

Learn more about the different voice settings [here](/docs/creative-platform/playground/text-to-speech#settings).

<Info>
  Voice changer adds an additional setting to automaticaly remove background noise from your
  recording.
</Info>

## Support languages

`eleven_english_sts_v2`

Our multilingual v2 models support 29 languages:

*English (USA, UK, Australia, Canada), Japanese, Chinese, German, Hindi, French (France, Canada), Korean, Portuguese (Brazil, Portugal), Italian, Spanish (Spain, Mexico), Indonesian, Dutch, Turkish, Filipino, Polish, Swedish, Bulgarian, Romanian, Arabic (Saudi Arabia, UAE), Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian & Russian.*

The `eleven_english_sts_v2` model only supports English.

[Learn more about models](/docs/overview/models)

## Best practices

Voice changer excels at **preserving accents** and **natural speech cadences** across various output voices. For instance, if you upload an audio sample with a Portuguese accent, the output will retain that language and accent. The input sample is crucial, as it determines the output characteristics. If you select a British voice like "George" but record with an American accent, the result will be George's voice with an American accent.

* **Expression**: Be expressive in your recordings. Whether shouting, crying, or laughing, the voice changer will accurately replicate your performance. This tool is designed to enhance AI realism, allowing for creative expression.
* **Microphone gain**: Ensure the input gain is appropriate. A quiet recording may hinder AI recognition, while a loud one could cause audio clipping.
* **Background Noise**: Turn on the **Remove Background Noise** option to automatically remove background noise from your recording.


# Sound effects

> How to create high-quality sound effects from text with ElevenLabs.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/iyHypKlscV0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

**Sound effects** enhance the realism and immersion of your audio projects. With ElevenLabs, you can generate sound effects from text and integrate them into your voiceovers and projects.

## Guide

<Steps>
  <Step title="Navigate to Sound Effects">
    Head over to [Sound Effects](https://elevenlabs.io/app/sound-effects). You can find it under
    **Playground** in the sidebar.
  </Step>

  <Step title="Describe the sound effect">
    In the text box, type a description of the sound effect you want (e.g., "person walking on
    grass").
  </Step>

  <Step title="Adjust settings">
    <Frame background="subtle">
      ![Sound effects
      settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3b14346a7ee375acc01d11b4ebb0ec0127a4a65bfab8e708d77ae5e639e64f38/assets/images/product-guides/sound-effects/sound-effects-settings.webp)
    </Frame>

    <ul>
      <li>
        Set the duration for the sound, or choose auto to let the AI decide. The maximum length is
        30 seconds.
      </li>

      <li>
        Turn <strong>Looping</strong> on to create a seamless loop. The ending will blend into the
        beginning without a noticeable gap.
      </li>

      <li>
        Adjust the prompt influence setting to control how closely the output should match the
        prompt. By default, this is set to 30%.
      </li>
    </ul>
  </Step>

  <Step title="Generate sound">
    Click the arrow to generate. Four sound effects will be created each time.
  </Step>

  <Step title="Review and regenerate">
    Go to your **History** tab to access the generated sound effects. Click the **download** icon
    and choose MP3 (44.1kHz) or WAV (48kHz). You can also click the **star** icon to save to your
    favorites, so you can access it again from your **Favorites** tab. If needed, adjust the prompt
    or settings and regenerate.
  </Step>
</Steps>

<Success>
  **Exercise**: Create a sound effect using the following prompt: Old-school funky brass stabs from
  a vinyl sample, stem, 88 bpm in F# minor.
</Success>

## Explore the library

<Frame background="subtle">
  ![Sound effects explore](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d8d7c3cca84e6acb0dfc419aed291be764794f299b2c7c478a9efc3f8f6e25ef/assets/images/product-guides/sound-effects/sound-effects-explore.png)
</Frame>

Browse community-made sound effects in the **Explore** tab.

For more on prompting and how sound effects work, visit our [overview page](/docs/overview/capabilities/sound-effects).


# Speech to Text

> A guide on how to transcribe audio with ElevenLabs

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0c8dba5ebba5f9a72541640bb4a9c9fac7bd265df0549f80cb5557c022f85b6f/assets/images/product-guides/speech-to-text/speech-to-text-product-feature.webp" alt="Text to Speech product feature" />

## Overview

With speech to text, you can transcribe spoken audio into text with state of the art accuracy. With automatic language detection, you can transcribe audio in a multitude of languages.

## Creating a transcript

<Steps>
  <Step title="Upload audio">
    In the ElevenLabs dashboard, navigate to the Speech to Text page and click the "Transcribe files" button. From the modal, you can upload an audio or video file to transcribe.

    <Frame background="subtle">
      ![Speech to Text upload](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/596c6fceacbe4659b583db3ba6e2ba0c1f55177cf870654ae5ded693f1ffe43b/assets/images/product-guides/speech-to-text/speech-to-text-modal.webp)
    </Frame>
  </Step>

  <Step title="Select options">
    * Select the primary language of the audio if you know it. You can leave this set to "Detect", and any languages within the audio will be automatically detected.

    * Choose whether you wish to tag audio events like laughter or applause using the "Tag audio events" toggle.

    * Keyterm prompting allows you to add up to 100 words or phrases to bias the model towards transcribing them. This is useful for transcribing specific words or sentences that are not common in the audio, such as product names, names, or other specific terms.

    When you're ready, click the "Upload files" button to submit.
  </Step>

  <Step title="View results">
    Click on the name of the audio file you uploaded in the center pane to view the results. You can click on a word to start a playback of the audio at that point.

    Click the "Export" button in the top right to download the results in a variety of formats.
  </Step>
</Steps>

## Transcript Editor

Once you've created a transcript, you can edit it in our Transcript Editor. Learn more about it [in this guide](/docs/creative-platform/products/transcripts).

## FAQ

<AccordionGroup>
  <Accordion title="What languages are supported?">
    ### Supported languages

    The Scribe v1 and v2 models support 90+ languages, including:

    *Afrikaans (afr), Amharic (amh), Arabic (ara), Armenian (hye), Assamese (asm), Asturian (ast), Azerbaijani (aze), Belarusian (bel), Bengali (ben), Bosnian (bos), Bulgarian (bul), Burmese (mya), Cantonese (yue), Catalan (cat), Cebuano (ceb), Chichewa (nya), Croatian (hrv), Czech (ces), Danish (dan), Dutch (nld), English (eng), Estonian (est), Filipino (fil), Finnish (fin), French (fra), Fulah (ful), Galician (glg), Ganda (lug), Georgian (kat), German (deu), Greek (ell), Gujarati (guj), Hausa (hau), Hebrew (heb), Hindi (hin), Hungarian (hun), Icelandic (isl), Igbo (ibo), Indonesian (ind), Irish (gle), Italian (ita), Japanese (jpn), Javanese (jav), Kabuverdianu (kea), Kannada (kan), Kazakh (kaz), Khmer (khm), Korean (kor), Kurdish (kur), Kyrgyz (kir), Lao (lao), Latvian (lav), Lingala (lin), Lithuanian (lit), Luo (luo), Luxembourgish (ltz), Macedonian (mkd), Malay (msa), Malayalam (mal), Maltese (mlt), Mandarin Chinese (zho), Māori (mri), Marathi (mar), Mongolian (mon), Nepali (nep), Northern Sotho (nso), Norwegian (nor), Occitan (oci), Odia (ori), Pashto (pus), Persian (fas), Polish (pol), Portuguese (por), Punjabi (pan), Romanian (ron), Russian (rus), Serbian (srp), Shona (sna), Sindhi (snd), Slovak (slk), Slovenian (slv), Somali (som), Spanish (spa), Swahili (swa), Swedish (swe), Tamil (tam), Tajik (tgk), Telugu (tel), Thai (tha), Turkish (tur), Ukrainian (ukr), Umbundu (umb), Urdu (urd), Uzbek (uzb), Vietnamese (vie), Welsh (cym), Wolof (wol), Xhosa (xho) and Zulu (zul).*
  </Accordion>

  <Accordion title="Can I upload video files?">
    Yes, the tool supports uploading both audio and video files. The maximum file size for either is 3GB.
  </Accordion>

  <Accordion title="Can I rename speakers?">
    ### Renaming speakers

    Yes, you can rename speakers by clicking the "edit" button next to the "Speakers" label.
  </Accordion>
</AccordionGroup>


# Image & Video

> Complete guide to creating and editing images and videos in ElevenLabs.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/BmMxkpm12vc" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Image & Video enables you to create high-quality visual content from simple text descriptions or reference images. Generate static images or dynamic videos in any style, then refine them iteratively with additional prompts, upscale for high-resolution output, and even add lip-sync with audio. Export finished assets as standalone files or import them directly into Studio projects.

<Note>
  This feature is currently in beta.
</Note>

<Info>
  Free plan users can only generate images. Video generation requires a paid plan.
</Info>

## Guide

Follow these steps to create your first visual asset:

<Steps>
  ### Select your mode

  Use the toggle in the upper right corner of the prompt box to choose between **Image** or **Video** generation.

  ### Provide a prompt or reference

  Describe your desired output using natural language in the prompt box. For more control, drag existing images or videos from the **Explore** or **History** tabs into the reference slots, or upload your own reference images in a wide range of file formats including JPG, PNG, WEBP, and more.

  ### Choose a model and settings

  Select the ideal generative model for your goal (e.g., OpenAI Sora 2 Pro, Google Veo 3.1, Kling 2.5, Flux 1 Kontext Pro). See the [Models](#models) section for detailed information on each model. Adjust settings like aspect ratio, resolution, duration (for video), and the number of variations to generate.

  ### Generate your asset

  Click the **[Generate](/docs/creative-platform/playground/image-video#generate-1)** button. Your assets will be created and displayed in the **[History](/docs/creative-platform/playground/image-video#history-1)** tab for review.

  ### Enhance and refine

  Use enhancement tools to perfect your media. **Upscale** the resolution, apply realistic **LipSync** with audio, or click **Recreate** to generate a new variation with the same settings.

  ### Share with others

  Click the **Share** button to generate a unique link for your creation. Send it to teammates and collaborators to collect feedback.

  ### Export your creation

  Download the asset as a standalone file or import it directly into a Studio project.
</Steps>

## Workflow

The creation process moves you from inspiration to finished asset in four stages:

### [Explore](/docs/creative-platform/playground/image-video#explore-1)

Discover community creations to find inspiration, study effective prompts, or pull references directly into your own work.

### [Generate](/docs/creative-platform/playground/image-video#generate-1)

Use the prompt box to describe what you want to create, select a model, fine-tune your settings, and bring your idea to life.

### [History](/docs/creative-platform/playground/image-video#history-1)

Review your generations in the History tab to iterate and enhance. Recreate variations, reuse prompts, and apply enhancements like upscaling and lip-syncing.

### [Export](/docs/creative-platform/playground/image-video#export-1)

Download finished assets in various formats or send them directly to Studio to use in your projects.

## Explore

The **Explore** tab displays a gallery of community creations for discovering inspiration and finding visuals to use as references.

**Search:** Use the search bar to find images and videos based on keywords.

**Sort:** Toggle between **Trending** and **Newest** to see what's popular or recently added.

**Drag-and-drop:** Pull any result from the grid directly into the prompt box to use as a start frame, end frame, or style reference.

**Preview details:** Click any tile to see the full prompt and settings used to create it.

## Generate

<Frame background="subtle">
  ![Video prompt interface](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/bc3b04f7acaf679807cbe014e4e084c3cb6126a7301b8a52bec3333f9674dfa4/assets/images/product-guides/images-videos/video-prompt.webp)
</Frame>

The prompt box is anchored at the bottom of the page and provides all controls for creating visual content.

### Set mode and prompt

**Select mode:** Use the toggle in the upper right corner to switch between **Image** and **Video** generation.

**Write your prompt:** In the main field, describe what you want to generate using natural language. Be clear and descriptive for best results.

### Choose models and settings

<Frame background="subtle">
  ![Video models selection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0ec9328b33378ba96df99818d263ae81ece738df8740c8cba257dcfbb8f75f07/assets/images/product-guides/images-videos/video-models.webp)
</Frame>

**Select model:** Open the model menu to browse available options like OpenAI Sora 2 Pro, Google Veo 3.1, Kling 2.5, or Flux 1 Kontext Pro. Each model has unique strengths and capabilities listed for easy comparison. See the [Models](#models) section for detailed information.

**Adjust settings:** Fine-tune your generation with settings that appear below the prompt. These vary by model but often include:

* **Aspect Ratio**: Control the dimensions of your output
* **Resolution**: Set the quality level
* **Duration**: Specify video length (for video mode)
* **Number of Generations**: Create up to 4 variations at once

**Use controls:** On supported models, enable **Audio**, add a **Negative Prompt** to exclude unwanted elements, or adjust **Sound Control**.

### Add references

<Frame background="subtle">
  ![Video references
  interface](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cb430f8e80b038841bc42eec541ac42046d4198802d6e9a5c1596e54bae032f1/assets/images/product-guides/images-videos/videos-prompt-references.webp)
</Frame>

For greater control over output, add visual references to guide generation. Availability depends on the selected model. We support a wide range of image file formats including JPG, PNG, WEBP, and more.

**Start Frame (Video):** Sets the opening image of your video.

**End Frame (Video):** Sets the final image, influencing the transition.

**Image Refs (Image or Video):** Provide one or more images to guide overall style and look.

<Tip>
  Drag and drop items directly from the **Explore** or **History** tabs into reference slots for a
  faster workflow.
</Tip>

### Generate

Before generating, a cost indicator shows the total cost for the number of assets you've chosen to create. When ready, click **Generate**. Your new creations will appear in the **History** tab.

## History

<Frame background="subtle">
  ![Video history interface](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c52ecc7d6d19fda705b1058c4b9b60c177b388d60d4e3e22492b2fe1bc35b16a/assets/images/product-guides/images-videos/video-history.webp)
</Frame>

The **History** tab provides a chronological log of everything you've generated and serves as a workspace for refining previous work.

**Browse:** View all past images and videos.

**Inspect:** Click any asset to see the original prompt, model, and settings used to create it.

**Reuse:** Drag items from History back into the prompt box to use as references for new generations.

**Iterate:** Click **Recreate** to run the same prompt and settings again for a new variation, or adjust settings to guide generation in a new direction.

**Share:** Click **Share** to generate a unique link for your asset. Send it to teammates and collaborators for feedback.

**Export:** Download your asset as a standalone file or click **Edit in Studio** to import it directly into Studio.

## Export

Once you have a generation you're satisfied with, use built-in enhancement tools before exporting.

### Enhancing your creations

**Upscale:** Use **Topaz Upscale** to increase resolution by up to 4x while preserving sharp details.

**LipSync:** Apply realistic lip-syncing to your visuals:

* **Omnihuman 1.5**: Animate a static image with an audio track
* **Veed LipSync**: Dub an existing video with new audio

### Exporting your assets

<Frame background="subtle">
  ![Video export interface](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e8a0b60eaa18b8f1f274d5813af93fbe592e7f8dd326d45f5121cc05ebbfa90c/assets/images/product-guides/images-videos/video-export.webp)
</Frame>

Export finished assets by downloading them locally or sending them directly to Studio.

**Edit in Studio:** Import the asset directly into a Studio project.

**Download:** Save the asset to your local machine.

## Supported download formats

**Video:**

* **MP4**: Codecs H.264, H.265. Quality up to 4K (with upscaling)

**Image:**

* **PNG**: High-resolution, lossless output

## Models

Image & Video provides access to specialized models optimized for different use cases. Each model offers unique capabilities, from rapid iteration to production-ready quality.

Post-processing models require an existing generated output, though you can also upload your own image or video file.

<AccordionGroup>
  <Accordion title="Video generative models">
    <AccordionGroup>
      <Accordion title="OpenAI Sora 2 Pro">
        The most advanced, high-fidelity video model for cinematic results at your disposal.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Highest-fidelity, professional-grade output with synced audio
        * Precise multi-shot control
        * Excels at complex motion and prompt adherence
        * Fixed durations: 4s, 8s, and 12s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Cinematic, professional-grade video content

        **Cost:** Starts at 12,000 credits for a generation

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound is enabled by default.
        </Note>
      </Accordion>

      <Accordion title="OpenAI Sora 2">
        The standard, high-speed version of OpenAI's advanced video model, tuned for everyday content creation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Realistic, physics-aware videos with synced audio
        * Fine scene control
        * Fixed durations: 4s, 8s, and 12s
        * Batch creation with up to 4 generations at a time
        * Strong narrative and character consistency

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Everyday content creation with realistic physics

        **Cost:** Starts at 4,000 credits for default settings

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound is enabled by default.
        </Note>
      </Accordion>

      <Accordion title="Google Veo 3.1">
        A professional-grade model for high-quality, cinematic video generation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame
        * Image References

        **Features:**

        * Excellent quality and creative control with negative prompts
        * Fully integrated and synchronized audio
        * Realistic dialogue, lip-sync, and sound effects
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time
        * Dedicated sound control

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * High-quality, cinematic video generation with full creative control

        **Cost:** Starts at 8,000 credits for default settings

        <Note>
          Enabling and disabling sound will change the generation credits.
        </Note>
      </Accordion>

      <Accordion title="Kling 2.5">
        A balanced and versatile model for high-quality, full-HD video generation.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Excels at simulating complex motion and realistic physics
        * Accurately models fluid dynamics and expressions
        * Fixed durations: 5s and 10s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 1080p
        * Aspect ratios: 16:9, 1:1, 9:16

        **Ideal for:**

        * Realistic physics simulations and complex motion

        **Cost:** Starts at 3,500 credits for default settings

        <Note>
          End frame is not currently supported. Cannot provide image references. Sound control not available.
        </Note>
      </Accordion>

      <Accordion title="Google Veo 3.1 Fast">
        A high-speed model optimized for rapid previews and generations, delivering sharper visuals with lower latency.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame

        **Features:**

        * Advanced creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time
        * Accurately models real-world physics for realistic motion and interactions

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Quick iteration and A/B testing visuals
        * Fast-paced social media content creation

        **Cost:** Starts at 4,000 credits for default settings
      </Accordion>

      <Accordion title="Google Veo 3">
        Production-ready model delivering exceptional quality, strong physics realism, and coherent narrative audio.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Advanced integrated "narrative audio" generation that matches video tone and story
        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Final renders and professional marketing content
        * Short-form storytelling

        **Cost:** Starts at 8,000 credits for default settings
      </Accordion>

      <Accordion title="Google Veo 3 Fast">
        A high-speed, cost-efficient model for generating audio-backed video from text or a starting image.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame

        **Features:**

        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 4s, 6s, and 8s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 720p, 1080p
        * Aspect ratios: 16:9, 9:16

        **Ideal for:**

        * Rapid iteration and previews
        * Cost-effective content creation

        **Cost:** Starts at 4,000 credits for default settings
      </Accordion>

      <Accordion title="Seedance 1 Pro">
        A specialized model for creating dynamic, multi-shot sequences with large movement and action.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame
        * End Frame

        **Features:**

        * Highly stable physics and seamless transitions between shots
        * Fixed durations: 3s, 4s, 5s, 6s, 7s, 8s, 9s, 10s, 11s, and 12s
        * Batch creation with up to 4 generations at a time
        * Maximum creative flexibility with numerous aspect ratio options

        **Output options:**

        * Resolutions: 480p, 720p, 1080p
        * Aspect ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Storytelling and action scenes requiring stable physics

        **Cost:** Starts at 4,800 credits for default settings

        <Note>
          Aspect ratio and resolution do not affect generation credits, but duration does.
        </Note>
      </Accordion>

      <Accordion title="Wan 2.5">
        A versatile model that delivers cinematic motion and high prompt fidelity from text or a starting image.

        **Generation inputs:**

        * Text-to-Video
        * Start Frame (Image-to-Video)

        **Features:**

        * Granular creative control with negative prompts and dedicated sound control
        * Fixed durations: 5s and 10s
        * Batch creation with up to 4 generations at a time

        **Output options:**

        * Resolutions: 480p, 720p, 1080p
        * Aspect ratios: 16:9, 1:1, 9:16

        **Ideal for:**

        * Cinematic content with strong prompt adherence

        **Cost:** Starts at 2,500 credits for default settings

        <Note>
          Generation cost varies based on selected settings.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Image generative models">
    <AccordionGroup>
      <Accordion title="Google Nano Banana">
        A high-speed model for quick, high-quality image generation and editing directly from text prompts.

        **Features:**

        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16

        **Ideal for:**

        * Rapid image creation and iteration

        **Cost:** Starts at 2,000 credits for default settings; varies based on number of generations
      </Accordion>

      <Accordion title="Seedream 4">
        A specialized image model for generating multi-shot sequences or scenes with large movement and action.

        **Features:**

        * Excels at creating images with stable physics and coherent transitions
        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: auto, 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Action scenes and dynamic compositions

        **Cost:** Starts at 1,200 credits for default settings; varies based on number of generations
      </Accordion>

      <Accordion title="Flux 1 Kontext Pro">
        A professional model for advanced image generation and editing, offering strong scene coherence and style control.

        **Features:**

        * Image-based style control requiring a reference image to guide visual aesthetic
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 21:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 9:21

        **Ideal for:**

        * Professional content with precise style requirements

        **Cost:** Starts at 1,600 credits; varies based on settings and number of generations
      </Accordion>

      <Accordion title="Wan 2.5">
        An image model with strong prompt fidelity and motion awareness, ideal for capturing dynamic action in a still frame.

        **Features:**

        * Granular control with negative prompts
        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16

        **Ideal for:**

        * Dynamic still images with motion awareness

        **Cost:** Starts at 2,000 credits; varies based on settings
      </Accordion>

      <Accordion title="OpenAI GPT Image 1">
        A versatile model for precise, high-quality image creation and detailed editing guided by natural language prompts.

        **Features:**

        * Supports multiple image references to guide generation
        * Generates up to 4 images at a time

        **Output options:**

        * Aspect ratios: 3:2, 1:1, 2:3
        * Quality options: low, medium, high

        **Ideal for:**

        * Creating and editing images with precise, text-based control

        **Cost:** Starts at 2,400 credits for default settings; varies based on settings and number of generations
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Lip-sync models">
    <AccordionGroup>
      <Accordion title="Omnihuman 1.5">
        A dedicated utility model for generating exceptionally realistic, humanlike lip-sync.

        **Inputs:**

        * Static source image
        * Speech audio file

        **Features:**

        * Animates the mouth on the source image to match provided audio
        * Creates high-fidelity "talking" video from still images
        * Lip-sync specific tool, not a full video generation model

        **Ideal for:**

        * Creating talking avatars
        * Adding dialogue to still images
        * Professional dubbing workflows

        **Cost:** Depends on generation input

        <Note>
          For best results, the image should contain a detectable figure.
        </Note>
      </Accordion>

      <Accordion title="Veed LipSync">
        A fast, affordable, and precise utility model for applying realistic lip-sync to videos.

        **Inputs:**

        * Source video
        * New speech audio file

        **Features:**

        * Re-animates mouth movements in source video to match new audio
        * Video-to-video lip-sync tool, not a full video generator

        **Ideal for:**

        * High-volume, cost-effective dubbing
        * Translating content
        * Correcting audio in video clips with realistic results

        **Cost:** Depends on generation input

        <Note>
          For best results, the video should contain a detectable figure.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Upscaling model">
    <AccordionGroup>
      <Accordion title="Topaz Upscale">
        A dedicated utility model for image and video upscaling, designed to enhance resolution and detail up to 4x.

        **Features:**

        * Enhancement tool that processes existing media
        * Increases media size while preserving natural textures and minimizing artifacts
        * Highly granular upscale factors: 1x, 1.25x, 1.5x, 1.75x, 2x, 3x, 4x
        * Video-specific: Flexible frame rate control (keep source or convert to 24, 25, 30, 48, 50, or 60 fps)

        **Ideal for:**

        * Improving quality of generated media
        * Restoring legacy footage or photos
        * Preparing assets for high-resolution displays

        **Cost:** Depends on generation input
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>


# Templates

> Curated combinations of AI models to create professional image, video, and audio content

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c0bbd347550f97f43ce7845fffd11aced095234d09e6a94d682a4d591ce989b0/assets/images/product-guides/workflows/workflows-overview.webp" alt="Templates overview" />

## Overview

Templates provides pre-configured templates that combine multiple AI tools into guided step-by-step processes. Each template is designed by our team of experts to help you achieve specific creative outcomes without needing to understand the technical details of model selection, parameter tuning, or file management.

With Templates, you can browse pre-made templates, customize them with your own inputs and settings, and generate high-quality outputs. The system automatically handles model selection, prompting, and file organization, allowing you to focus on your creative vision.

<Note>
  This feature is currently in beta.
</Note>

## Guide

<Steps>
  ### Browse the gallery

  Navigate to the **Explore** tab to view available templates. Each template shows a preview of the expected output and the steps involved.

  ### Select a template

  Choose a template that matches your desired outcome. Click on it to view the full details and requirements.

  ### Follow the steps

  Complete each step in sequence, providing your custom inputs such as images, prompts, or settings. You can pause at any time and resume later from the **History** tab.

  ### Review outputs

  After completing the template, review your generated content. Depending on the template type, you will see options to continue editing in other tools, upscale your output, or download to your computer.

  ### Template history

  View all previous template executions in the **History** tab. You can resume partial generations or review completed work.
</Steps>

<Note>
  Completed templates automatically appear in the history of related products (e.g., Image & Video,
  Music) so you can continue iterating outside of Templates.
</Note>

## How it works

<Frame background="subtle">
  ![Templates detail](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a57b0308fedfbdf41cb1a95c038e38dbe8201388dee859e83d11af5fe86e17a7/assets/images/product-guides/workflows/workflows-detail.webp)
</Frame>

With Templates, we've created automated sequences that handle model and prompt selection for you, ensuring consistent, high-quality results. Each template specifies:

* Model selection for each generation step
* Pre-engineered prompts optimized for specific outcomes
* Parameter configurations tested for quality results
* File management and organization between steps

When you complete a template, the generated content appears in your history for the corresponding product. You can inspect the settings, models, and prompts used to understand how the output was created and replicate the process manually if desired.

## Featured templates

<CardGroup cols={2}>
  <Card title="Avatars" icon="duotone user" iconPosition="left">
    Select a pre-made avatar, upload an image of a prop, and generate a personalized video message.
  </Card>

  <Card title="Bring images to life" icon="duotone image" iconPosition="left">
    Upload photos and animate them with realistic motion and expressions.
  </Card>

  <Card title="Santa messages" icon="duotone gift" iconPosition="left">
    Generate personalized holiday messages from Santa addressed to specific recipients.
  </Card>

  <Card title="Video to music" icon="duotone music" iconPosition="left">
    Upload a video and generate a custom soundtrack that matches the mood and pacing.
  </Card>
</CardGroup>

## Key features

<AccordionGroup>
  <Accordion title="Pre-configured model chains">
    #### Pre-configured model chains

    Each template selects the optimal model for each step based on extensive testing. You don't need to understand which models work best together or how to configure them for specific use cases.
  </Accordion>

  <Accordion title="Optimized prompts">
    #### Optimized prompts

    Templates include prompt engineering developed by our team. This reduces the number of iterations needed to achieve high-quality results compared to manual prompting.
  </Accordion>

  <Accordion title="Guided process">
    #### Guided process

    Step-by-step instructions make it clear what inputs are required and what to expect at each stage. You don't need to memorize complex procedures or refer to documentation.
  </Accordion>

  <Accordion title="Automated file transfers">
    #### Automated file transfers

    Templates handle intermediate files and outputs automatically. You don't need to manage file transfers between different tools or keep track of which files to use for each step.
  </Accordion>

  <Accordion title="Resumable execution">
    #### Resumable execution

    For multi-step templates, you can stop at any point and resume later. Your progress is saved automatically in the **History** tab.
  </Accordion>
</AccordionGroup>

## Billing and pricing

Templates use the same pricing as running the individual models manually. There is no additional markup for using Templates.

<Note>
  Price estimates are shown before each step when possible. Some templates (e.g., LipSync) cannot
  provide exact prices upfront due to variable processing requirements.
</Note>

Credit usage is calculated based on:

* Model type used for each generation step
* Duration or size of the output
* Number of variants or iterations

All credit costs are transparently displayed before you confirm each generation step.

## FAQ

<AccordionGroup>
  <Accordion title="Can I modify templates or create my own?">
    Templates are currently curated by the ElevenLabs team. You cannot modify existing templates or create custom ones. If you need more control, you can replicate the process manually using the individual tools after inspecting the template's settings in your history.
  </Accordion>

  {' '}

  <Accordion title="Where do my template outputs go?">
    Completed template outputs appear in the **History** tab within Templates. They also appear in the
    history of the corresponding product (e.g., Image & Video, Music) so you can continue editing
    using those tools.
  </Accordion>

  {' '}

  <Accordion title="Can I resume a template I started earlier?">
    Yes. Navigate to the **History** tab to see all templates in progress. Click on a partial template
    to resume from where you left off.
  </Accordion>

  {' '}

  <Accordion title="Are templates more expensive than manual processes?">
    No. Templates use the same per-model pricing as manual execution. You pay only for the models and
    generations used, with no additional fees.
  </Accordion>

  {' '}

  <Accordion title="Can I see what settings were used in a template?">
    Yes. After completing a template, you can view the models, prompts, and settings used by checking
    your history in the corresponding product. This transparency allows you to learn from templates
    and replicate them manually if desired.
  </Accordion>

  <Accordion title="What if I'm not happy with the output?">
    Depending on where the template outputs to (e.g., Image & Video, Music), you can continue iterating using that product's editing tools. You can also restart the template with different inputs or settings.
  </Accordion>
</AccordionGroup>


# Studio

> Create professional video and audio content with our end-to-end production workflow

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/864735473270d21a96e0ddac8e875fade225b6ec6c29aab91f55c780300c0cda/assets/images/product-guides/studio/studio-timeline-overview.webp" alt="Studio timeline overview" />

## Overview

Studio provides an end‑to‑end workflow for creating video and audio content.

With Studio 3.0, you can now add a dedicated **timeline** with a **video track** and **captions** so you can build complete voiceovers. You can also layer **music** and **sound effects** on separate tracks, import external **audio**, and fine‑tune timing down to individual sentences. Once your project is ready for feedback, you can use our new **sharing** and **commenting** features to gather feedback from teammates.

Finally, you can **export** your work in various audio formats (per chapter or whole project) or as a video if a video track was included.

<Note>
  Studio supports our latest speech models, including v3. You can switch models at any time in
  **Project settings**.
</Note>

## Guide

<Frame background="subtle">
  ![Studio create](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5187ef192deeed519d504c210f38b13c0e4cc23d8ff832de23402cdcc6b8aa60/assets/images/product-guides/studio/studio-home.webp)
</Frame>

<Steps>
  <Step title="Create a new project">
    Select one of the starting options at the top of the Studio page.
  </Step>

  <Step title="Select settings">
    Follow the instructions in the pop-up and click 

    **Create**

    .
  </Step>

  <Step title="Enhance your project">
    Add **video**, **narration**, **music**, and **sound effects** to your project using our
    timeline editor.
  </Step>

  <Step title="Collaborate with others">
    Click the **Share** button to share your project and collect feedback from teammates.
  </Step>

  <Step title="Export your project">
    Click the **Export** button to export the project as audio or video.
  </Step>
</Steps>

<Note>
  You can use our [Audio Native](/docs/creative-platform/audio-tools/audio-native) feature to easily
  and effortlessly embed any Studio audio project onto your website.
</Note>

## Starting options

Some settings are automatically selected by default when you create a new project.

The default model is Multilingual v2 for most new projects. You can also choose newer models, including v3, in **Project Settings**.

The quality setting is automatically selected depending on your subscription plan, and will not increase your credit usage.

For free, Starter and Creator subscriptions the quality will be 128 kbps MP3, or WAV generated from 128 kbps source.

For Pro, Scale, Business and Enterprise plans, the quality will be 16-bit, 44.1 kHz WAV, or 192 kbps MP3 (Ultra Lossless).

<Info>
  Video exports on free and Starter plans include a watermark. To export videos without a watermark,
  you need a Creator plan or above.
</Info>

### Quick start

<AccordionGroup>
  <Accordion title="Upload">
    #### Upload

    Upload a file to start from existing media. We’ll analyze it and choose the best layout automatically: text or audio uploads open in the **audio** layout; video files open in the **video** layout with the timeline and **captions** available.
  </Accordion>

  <Accordion title="Start audio project from scratch">
    #### Start audio project from scratch

    Create a blank audio project and begin writing your script. Add **voices**, **music**, and **sound effects** later from the **timeline**.
  </Accordion>

  <Accordion title="Start video project from scratch">
    #### Start video project from scratch

    Create a blank video project with a **video track** ready to add footage, voiceover, and **captions**.
  </Accordion>
</AccordionGroup>

### Audio

<AccordionGroup>
  <Accordion title="New audiobook">
    #### New audiobook

    <Frame background="subtle">
      ![Create an audiobook](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/89d8cf2e96dc5792714da6d6cc12d5796c85c2127000c81890972b08d4c3f502/assets/images/product-guides/studio/studio-create-audiobook.webp)
    </Frame>

    You’ll see a pop‑up to upload a file; we’ll import it into your new project.

    You can upload EPUB, PDF, TXT, HTML, and DOCX files.

    You can also select a default voice and optionally enable **Auto‑assign voices** to detect characters and assign matching voices. This adds some processing time.
  </Accordion>

  <Accordion title="Create a podcast">
    #### Create a podcast

    <Frame background="subtle">
      ![Create a podcast](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4289bcc30b99f08b9dc309e80f8d770e22d0de7c8352ae7a5b9d2051f60a658b/assets/images/product-guides/studio/studio-create-podcast.webp)
    </Frame>

    This option will use GenFM to automatically create a podcast based on an uploaded document, a webpage via URL, or an existing project.

    <Note>
      With this option, GenFM will generate a new script from your source. If you want to keep your script unchanged, use **New audiobook** or **Start audio project from scratch**.
    </Note>

    In the format settings, choose a conversation between a host and guest, or a more focused bulletin‑style podcast with a single host. You can also set the duration to short, default, or long.

    You can choose your own preferred voices for the host and guest, or go with our suggested voices.

    You can set the podcast language; if you don’t, it will match the language of the source material.

    Use the **cog** icon to open advanced configuration and specify up to three focus areas.
  </Accordion>

  <Accordion title="URL to audio">
    #### URL to audio

    <Frame background="subtle">
      ![Create an article](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/59d699e7839a8721c3eda06f3871cc4ff3b7fd69c17d68da94275f8de5a3c030/assets/images/product-guides/studio/studio-create-article.webp)
    </Frame>

    You’ll see a pop‑up to enter a URL; we’ll import the page text into your project.

    You can also select a default voice for your project and optionally enable **Auto‑assign voices** to detect characters and assign matching voices. This adds some processing time.
  </Accordion>

  <Accordion title="AI Script Generator">
    #### AI Script Generator

    Describe what you want and let the AI draft a script for you. Review the script, make edits, and start a new audio project from it.
  </Accordion>
</AccordionGroup>

### Video

<AccordionGroup>
  <Accordion title="New video voiceover">
    #### New video voiceover

    Create a project optimized for video voiceovers. Import your video, transcribe or generate narration, and enable **captions** with a chosen template.
  </Accordion>

  <Accordion title="Enhance your video">
    #### Enhance your video

    Upload a video and let Studio suggest fitting **music** and **sound effects**. Tweak the mix on the **timeline**.
  </Accordion>

  <Accordion title="Add captions">
    #### Add captions

    Open the **Captions** tab by default to transcribe narration or imported audio, then style captions with templates and positioning.
  </Accordion>

  <Accordion title="Remove background noise">
    #### Remove background noise

    Upload a video and reduce background noise in the audio track. Proceed to add voiceover, music, and SFX as needed.
  </Accordion>

  <Accordion title="Fix voiceover mistakes">
    #### Fix voiceover mistakes

    Upload a video and we’ll automatically transcribe the audio, flag potential misreads or timing issues, and help correct them with targeted speech regeneration.
  </Accordion>

  <Accordion title="AI Soundtrack Generator">
    #### AI Soundtrack Generator

    Automatically generate music that matches your video’s mood and pacing, then place it on a dedicated music track.
  </Accordion>
</AccordionGroup>

## Generating and Editing

Once you've added content, either by importing it or creating it yourself, you can use the **Export**
button to render your chapter or project in one step. Narration will be generated where needed, and the output will be audio or video depending on your tracks and settings.

<Frame background="subtle">
  ![Export your project](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/16b43de5083533757e672144636ec22abfde7be1e7e885ee786136e17e07ce36/assets/images/product-guides/studio/studio-export.webp)
</Frame>

This will automatically generate and download an audio or video file, but you can still edit your project after this.

Once you've finished editing, you will need to use the **Export** button again to generate and download a new
version of your project that includes the updated media.

<AccordionGroup>
  <Accordion title="Timeline and tracks">
    #### Timeline and tracks

    <Frame background="subtle">
      ![Studio timeline editing](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c0e5e49ff7bc0927942486450ea88f5065796244e5da225c01ac2e2962b80c64/assets/images/product-guides/studio/studio-timeline-editing.webp)
    </Frame>

    The **timeline** gives you a chapter‑wide view of your project so you can see narration, music, SFX, and video at a glance.

    You can **adjust timing** between paragraphs and even individual sentences, **trim** clip edges, **split** and **duplicate** clips to iterate quickly, and **zoom** or **pan** to navigate longer chapters. **Waveforms** help you visualize loudness so you can align levels precisely across tracks.
  </Accordion>

  <Accordion title="Contextual sidebar">
    #### Contextual sidebar

    <Frame background="subtle">
      ![Contextual sidebar](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9fed95483172d885743ee137ed9cf6d63eaf91cc73224adb06432d1774e3454f/assets/images/product-guides/studio/studio-voices.webp)
    </Frame>

    The Contextual sidebar shows tools and details for the currently selected item in your project.
    For narration, you'll see **voice** and **delivery** controls; for media clips (audio, music, SFX,
    or video), you'll see relevant **clip properties** and actions.
  </Accordion>

  <Accordion title="Chapters sidebar">
    #### Chapters sidebar

    When you create a Studio project using the **Create an audiobook** option and import a document that includes chapters, chapters will be automatically enabled for your project. You can toggle the visibility of the Chapters sidebar by clicking **Chapters**.

    <Frame background="subtle">
      ![Studio chapters toggle](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/577314657f97766bfa1e7c69438f2015284b3bc9e2e947d1a2b37b43e3e2ad0d/assets/images/product-guides/studio/studio-chapters-toggle.webp)
    </Frame>

    If you want to add a new chapter, you can do this using the **+** button at the top of the Chapters
    sidebar.

    If you used the **Start from scratch** option to create your project, or your project didn't originally include chapters, you'll need to enable chapters in **Project settings**. You will find the **Enable chapters** toggle in the general settings.

    <Frame background="subtle">
      ![Enable chapters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b245af4af9a6cb1aff070bfead43f8b21c50e4a31be1faaf6bbbde21b490bef6/assets/images/product-guides/studio/studio-enable-chapters.webp)
    </Frame>

    Once you've enabled chapters, you can click **+ Chapter** to add a new chapter to your project. After you've added one chapter, the Chapters sidebar will be enabled, and you can use the **+** button to add additional chapters.
  </Accordion>

  <Accordion title="Generate/Regenerate">
    #### Generate/Regenerate

    <Frame background="subtle">
      ![Generate/Regenerate](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/200d8c760407d73331ebe2486ef3d72b9f9e0c38418f2f7a6b1b98644a9412e6/assets/images/product-guides/studio/studio-generate.webp)
    </Frame>

    The **Generate** button will generate audio if you have not yet generated audio for the selected
    text, or will generate new audio if you have already generated audio. This will cost credits.

    If you have made changes to the paragraph such as changing the text or the voice, then the paragraph
    will lose its converted status, and will need to be generated again.

    The status of a paragraph (converted or unconverted) is indicated by the bar to the left of the paragraph.
    Unconverted paragraphs have a pale grey bar while converted paragraphs have a dark grey bar.

    If the button says **Regenerate**, then this means that you won't be charged for the next generation.
    You're eligible for two free regenerations provided you don't change the voice or the text.

    This action applies to narration and other generated speech. Timeline items like video, external audio, music, SFX, and captions are arranged on the timeline and rendered when you export.
  </Accordion>

  <Accordion title="Play">
    #### Play

    <Frame background="subtle">
      ![Play button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a809c5383fed059e56f2d07b3449fd51174f7f0271b88127323eae1e90f65a98/assets/images/product-guides/studio/studio-play.webp)
    </Frame>

    You can use the **Play** button in the player at the bottom of the Studio interface to play audio
    that has already been generated, or generate audio if a paragraph has not yet been converted.
    Generating audio will cost credits. If you have already generated audio, then the **Play** button
    will play the audio that has already generated and you won't be charged any credits. There are two
    modes when using the **Play** button. **Until end** will play existing audio, or generate new
    audio for paragraphs that have not yet been generated, from the selected paragraph to the end of
    the current chapter. **Selection** will play or generate audio only for the selected paragraph.
    When a video track is present, the player also previews video in sync with the playhead. Playing
    existing audio or video never consumes credits; only generating narration does.
  </Accordion>

  <Accordion title="Generation history">
    #### Generation history

    <Frame background="subtle">
      ![Generation History
      button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5a7c35867553a691ee6b8e9bb4ebead90ac05e30b5bcc2b3622e25003fc5c14e/assets/images/product-guides/studio/studio-generation-history-btn.webp)
    </Frame>

    If you click the **Generation history** button, this will show all the previously generated audio
    for the selected paragraph. This allows you to listen to and download each individual generation.

    <Frame background="subtle">
      ![Generation History](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e59179dbc88f9dc4a51f5631a8f8e53de4a3177a68b48eddbcd782633682fb00/assets/images/product-guides/studio/studio-generation-history.webp)
    </Frame>

    If you prefer an earlier version of a paragraph, you can restore it to that previous version.
    You can also remove generations, but be aware that if you
    remove a version, this is permanent and you can't restore it.

    Generation history applies to narration generations. It doesn't track imported media (external audio, music, SFX) or video clips.
  </Accordion>

  <Accordion title="Undo and Redo">
    #### Undo and Redo

    <Frame background="subtle">
      ![Undo and Redo](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2d2bfa6b815f479f46cd68f4820e9cd9cab92f156cb068a195047d5815410528/assets/images/product-guides/studio/studio-undo-redo.webp)
    </Frame>

    If you accidentally make a change, you can use the **Undo** button to restore the previous
    version, and the **Redo** button to restore the change.
  </Accordion>

  <Accordion title="Breaks">
    #### Breaks

    <Frame background="subtle">
      ![Breaks](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0af086c3e5739251d9dadce0f147f9ad48a37f085d53adfaabcb0e2abd5b532e/assets/images/product-guides/studio/studio-break.webp)
    </Frame>

    You can add a pause by using the **Insert break** button. This inserts a break tag. By default, this will be set to 1 second, but you can change the length of the break up to a maximum of 3 seconds.

    <Note>
      For precise timing, prefer the timeline with trimming and sentence‑level control. Some newer models may
      reduce or ignore break tags in favor of natural flow.
    </Note>

    Breaks affect generated speech delivery only; they don't move or pause other timeline tracks. Use the timeline to create precise pauses across music, SFX, and video.
  </Accordion>

  <Accordion title="Actor Mode">
    #### Actor Mode

    <Frame background="subtle">
      ![Actor Mode](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/678c1a129fc4484ab5c8dd2f73d3978b4bf6aabaacd5e9cc16a26679da52b0af/assets/images/product-guides/studio/studio-actor-mode.webp)
    </Frame>

    Actor Mode allows you to specify exactly how you would like a section of text to be delivered by uploading a recording, or by recording yourself directly. You can either highlight a selection of text that you want to work on, or select a whole paragraph. Once you have selected the text you want to use Actor Mode with, click the **Actor Mode** button, and the Actor Mode pop-up will appear.

    For an overview of Actor Mode, see [this video](https://www.youtube.com/watch?v=Kj2dgXITrPw).

    <Frame background="subtle">
      ![Actor Mode pop-up](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c4330227d2e0a5771a62dca62d377f037b48559f706c790daa83e2328af868c4/assets/images/product-guides/studio/studio-actor-mode-popup.webp)
    </Frame>

    Either upload or record your audio, and you will then see the option to listen back to the audio or remove it. You will also see how many credits it will cost to generate the selected text using the audio you've provided.

    <Frame background="subtle">
      ![Actor Mode pop-up](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2bde62b614183de32d30aad603c04f376002c21de59afa3dfaf2ebba677dbc9e/assets/images/product-guides/studio/studio-actor-mode-popup-2.webp)
    </Frame>

    If you're happy with the audio, click **Generate**, and your audio will be used to guide the delivery of the selected text.

    <Note>
      Actor Mode will replicate all aspects of the audio you provide, including the accent.
    </Note>
  </Accordion>

  <Accordion title="Video track and voiceovers">
    #### Video track and voiceovers

    <Frame background="subtle">
      ![Studio video track](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b7f028bef5716fd9ec60885ac8449584ec6f6bd38a110618c07f002f283ecd8e/assets/images/product-guides/studio/studio-video-track.webp)
    </Frame>

    Add a **video track** to voice over existing footage or to pair narration with b‑roll. Import a video file or add a blank track, then align the narration to key visual beats on the timeline. When needed, enable **captions** and choose a **template** to match your style.
  </Accordion>

  <Accordion title="Captions">
    #### Captions

    <Frame background="subtle">
      ![Studio caption templates](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0f336e754e6bd6b507498d51b2475cf833fae292d4a453e920d3f7b4d512f48d/assets/images/product-guides/studio/studio-caption-templates.webp)
    </Frame>

    Convert narration into styled **captions** for accessibility and engagement. Captions are generated automatically and can be customized with **templates** for colors, fonts, and placement. Edit text and timing directly on the **timeline** to correct any mismatches, then export your video with **burned‑in captions**.
  </Accordion>

  <Accordion title="External audio">
    #### External audio

    **Import** your own audio files—such as dialogue, stingers, or ambience—and mix them with narration, music, and SFX. Drag files into the **timeline** or use the import action, then **trim**, **split**, **duplicate**, and adjust clip volume as needed. **Stereo** files remain stereo on export.

    <Frame background="subtle">
      ![Insert audio](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f5524cdd6cd459fe97e2ff3e6c248e84485844c76ed4f8305d78a13941f594b2/assets/images/product-guides/studio/studio-audio.webp)
    </Frame>
  </Accordion>

  <Accordion title="Music">
    #### Music

    Generate **music** directly in Studio and place it on its own track in the timeline. Create new songs from **prompts** (choose a vibe and length) or **import** existing tracks. Music clips can be **trimmed**, **duplicated**, and moved to match the narration, and you can adjust **volume** per clip. When the source is **stereo**, stereo is preserved.

    <Frame background="subtle">
      ![Insert music](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3f700d0ad73438a33cf7dde9445c0211092a212805dc4c6473195c006bb1aa94/assets/images/product-guides/studio/studio-music.webp)
    </Frame>
  </Accordion>

  <Accordion title="Sound effects">
    #### Sound effects

    <Frame background="subtle">
      ![Insert sound effect](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9e9e7f60f2a2640acd8221fb0c06d0991f70ca1e5ebd24aab32f39e899248cd1/assets/images/product-guides/studio/studio-sound-effect.webp)
    </Frame>

    Add **sound effects** as separate clips on the timeline. You can position them anywhere, layer multiple effects, and adjust their timing precisely with trimming and duplication.

    You can create effects from a text prompt inside Studio or browse and insert items from the **SFX library**.

    You can regenerate previews to explore variants and then apply your chosen effect to the timeline. Deleting and duplicating SFX clips works the same as other timeline clips.

    <Note>
      Sound effects are not supported in ElevenReader exports, or when streaming the project using the Studio API.
    </Note>
  </Accordion>

  <Accordion title="Lock paragraph">
    #### Lock paragraph

    <Frame background="subtle">
      ![Lock paragraph Button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7966c5e5017d1c34944898e9f105cb75f12a0643a20853c31aeb8e9aeec3326e/assets/images/product-guides/studio/studio-lock.webp)
    </Frame>

    Once you're happy with the performance of a paragraph, you can use the **Lock paragraph** button
    to prevent any further changes.

    <Frame background="subtle">
      ![Locked paragraph](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/dad2aea00d4161889d8cf55256f8a01fcd2863cc130a474bda66b7928252c547/assets/images/product-guides/studio/studio-locked-paragraph.webp)
    </Frame>

    Locked paragraphs are indicated by a lock icon to the left of the paragraph. If you want to unlock
    a paragraph, you can do this by clicking the **Lock paragraph** button again. Locking applies to
    narration content; you can continue editing timeline clips like video, music, and SFX.
  </Accordion>

  <Accordion title="Keyboard shortcuts">
    #### Keyboard shortcuts

    <Frame background="subtle">
      ![Keyboard Shortcuts](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/be37aad7c3e0546a5c35fdbec5cac28a3e76de42e50c0c7c019fde4be5465d64/assets/images/product-guides/studio/studio-keyboard-shortcuts.webp)
    </Frame>

    There are a range of keyboard shortcuts that can be used in Studio to speed up your workflow. To
    see a list of all available keyboard shortcuts, click the **Project options** button, then select
    **Keyboard shortcuts**.
  </Accordion>
</AccordionGroup>

## Settings

<AccordionGroup>
  <Accordion title="Voices">
    ### Voices

    We offer many types of voices, including the curated Default Voices library; completely synthetic voices created using our Voice Design tool; and you can create your own collection of cloned voices using our two technologies: Instant Voice Cloning and Professional Voice Cloning. Browse through our voice library to find the perfect voice for your production.

    Not all voices are equal, and a lot depends on the source audio used to create that voice. Some voices will perform better than others, while some will be more stable than others. Additionally, certain voices will be more easily cloned by the AI than others, and some voices may work better with one model and one language compared to another. All of these factors are important to consider when selecting your voice.

    If you’re unhappy with a voice, but you’re happy with the delivery of the narration, you can use our Voice Changer functionality to change the voice, but preserve the narration

    [Learn more about voices](/docs/overview/capabilities/voices)
  </Accordion>

  <Accordion title="Voice settings">
    ### Voice settings

    <Frame background="subtle">
      ![Studio voice settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/79244f2adcaf72c3811c806e92db073be60dd536131fca32b637c6df837fdced/assets/images/product-guides/studio/studio-voice-settings.webp)
    </Frame>

    Our users have found different workflows that work for them. The most common setting is stability around 50 and similarity near 75, with minimal changes thereafter. Of course, this all depends on the original voice and the style of performance you're aiming for.

    It's important to note that the AI is non-deterministic; setting the sliders to specific values won't guarantee the same results every time. Instead, the sliders function more as a range, determining how wide the randomization can be between each generation.

    If you have a paragraph or text selected, you can use the **Override settings** toggle to change the settings for just the current selection. If you change the settings for the voice without enabling this, then this will change the settings for this voice across the whole of your project. This will mean that you will need to regenerate any audio that you had previously generated using different settings. If you have any locked paragraphs that use this voice, you won't be able to change the settings unless you unlock them.

    #### Alias

    You can use this setting to give the voice an alias that applies only for this project. For example, if you're using a different voice for each character in your audiobook, you could use the character's name as the alias.

    #### Volume

    If you find the generated audio for the voice to be either too quiet or too loud, you can adjust the volume. The default value is 0.00, which means that the audio will be unchanged. The minimum value is -30 dB and the maximum is +5 dB.

    #### Speed

    The speed setting allows you to either speed up or slow down the speed of the generated speech. The default value is 1.0, which means that the speed is not adjusted. Values below 1.0 will slow the voice down, to a minimum of 0.7. Values above 1.0 will speed up the voice, to a maximum of 1.2. Extreme values may affect the quality of the generated speech.

    #### Stability

    The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice. This is influenced heavily by the original voice. Setting the slider too low may result in odd performances that are overly random and cause the character to speak too quickly. On the other hand, setting it too high can lead to a monotonous voice with limited emotion.

    For a more lively and dramatic performance, it is recommended to set the stability slider lower and generate a few times until you find a performance you like.

    On the other hand, if you want a more serious performance, even bordering on monotone at very high values, it is recommended to set the stability slider higher. Since it is more consistent and stable, you usually don't need to generate as many samples to achieve the desired result. Experiment to find what works best for you!

    #### Similarity

    The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. If the original audio is of poor quality and the similarity slider is set too high, the AI may reproduce artifacts or background noise when trying to mimic the voice if those were present in the original recording.

    #### Style exaggeration

    With the introduction of the newer models, we also added a style exaggeration setting. This setting attempts to amplify the style of the original speaker. It does consume additional computational resources and might increase latency if set to anything other than 0. It's important to note that using this setting has shown to make the model slightly less stable, as it strives to emphasize and imitate the style of the original voice.

    In general, we recommend keeping this setting at 0 at all times.

    #### Speaker boost

    This setting boosts the similarity to the original speaker. However, using this setting requires a slightly higher computational load, which in turn increases latency. The differences introduced by this setting are generally rather subtle.
  </Accordion>

  <Accordion title="Pronunciation dictionaries">
    ### Pronunciation dictionaries

    <Frame background="subtle">
      ![Studio pronunciation dictionaries](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/529a45f8a99dd533047caade26211cacfae53245a43f791efe34d8723555619c/assets/images/product-guides/studio/studio-pronunciation-dictionaries.webp)
    </Frame>

    Sometimes you may want to specify the pronunciation of certain words, such as character or brand names, or specify how acronyms should be read. Pronunciation dictionaries allow this functionality by enabling you to upload a lexicon or dictionary file that includes rules about how specified words should be pronounced, either using a phonetic alphabet (phoneme tags) or word substitutions (alias tags).

    <Note>
      Phoneme tags are only compatible with "Eleven Flash v2", "Eleven Turbo v2" and "Eleven English v1"
      [models](/docs/overview/models).
    </Note>

    Whenever one of these words is encountered in a project, the AI will pronounce the word using the specified replacement. When checking for a replacement word in a pronunciation dictionary, the dictionary is checked from start to end and only the first replacement is used.

    Existing pronunciation dictionaries can be connected to your project from the Pronunciations Editor. You can open this from the toolbar. Find the dictionary you want to connect in the drop down menu and select **Connect**.

    You can create a new pronunciation dictionary from your project by creating an entry in the Pronunciations Editor, or you can upload or create a pronunciation dictionary from **Open all pronunciation dictionaries** in the Pronunciations Editor. You can then select **Connect** to connect the pronunciation dictionary to the current project.

    For more information on pronunciation dictionaries, please see our [prompting best practices guide](/docs/overview/capabilities/text-to-speech/best-practices#pronunciation-dictionaries).
  </Accordion>

  <Accordion title="Export settings">
    ### Export settings

    Within the **Export** tab under **Project settings** you can add additional metadata such as Title, Author, ISBN and a Description to your project. This information will automatically be added to the downloaded audio files. You can also access previous versions of your project, and enable volume normalization. These settings apply to audio exports; video appearance is controlled by your timeline and caption templates.
  </Accordion>
</AccordionGroup>

## Exporting and Sharing

When you're happy with your chapter or project, use the **Export** button to generate a downloadable version. If you've already generated audio for every paragraph in either your chapter or project, you won't be charged any additional credits to export. If there are any paragraphs that do need converting as part of the export process, you will see a notification of how many credits it will cost to export.

<Info>
  Video exports on free and Starter plans include a watermark. To export videos without a watermark,
  you need a Creator plan or above.
</Info>

<AccordionGroup>
  <Accordion title="Export options">
    #### Export options

    If your project only has one chapter, you will just see the option to export as either MP3 or WAV (audio), or as video when a video track/captions are present.

    If your project has multiple chapters, you will have the option to export each chapter individually, or export the full project. If you're exporting the full project, you can either export as a single file, or as a ZIP file containing individual files for each chapter. You can also choose whether to download as MP3 or WAV for audio‑only exports.

    For video exports, enable captions and add a video track (or shareable TTS video) before exporting. Video is rendered with your selected caption template.
  </Accordion>

  <Accordion title="Quality setting">
    #### Quality setting

    The quality of the export depends on your subscription plan. For newly created projects, the quality will be:

    * Free, Starter and Creator: 128 kbps MP3, or WAV converted from 128 kbps source.
    * Pro, Scale, Business and Enterprise plans: 16-bit, 44.1 kHz WAV, or 192 kbps MP3 (Ultra Lossless).

    <Note>
      If you have an older project, you may have set the quality setting when you created the project, and this can't be changed. You can check the quality setting for your project in the Export menu by hovering over **Format**
    </Note>
  </Accordion>

  <Accordion title="Downloading">
    #### Downloading

    Once your export is ready, it will be automatically downloaded. For shareable TTS videos, you can also copy a link for quick sharing.

    You can access and download all previous exports, of both chapters and projects, by clicking the **Project options** button and selecting **Exports**.
  </Accordion>

  <Accordion title="Sharing">
    #### Sharing

    From the editor, create a **read‑only link** so others can play your timeline and review your mix without downloading files. You can revoke access at any time. **Commenting** is available at launch, including anonymous comments.

    <Frame background="subtle">
      ![Studio share project](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f2cf13471019a920e4b8483b40fb4a92b6d70f85da6bdfd82a7560287fa20efd/assets/images/product-guides/studio/studio-share-project.webp)
    </Frame>
  </Accordion>

  <Accordion title="Commenting">
    #### Commenting

    Invite collaborators or your audience to leave feedback directly on the timeline. Comments are timestamped to the playhead so feedback appears exactly where it’s relevant. Commenters don’t need an ElevenLabs account and can leave a name or post anonymously. Discussions stay organized with **threaded replies** and optional **mentions** of collaborators.

    To add a comment, open a shared project link (or the editor with sharing enabled), move the playhead to the right moment, and click **Add comment**. Type your message and post; use **Reply** to continue the thread. You’ll receive **email notifications** when there’s a new comment or reply in a thread you started or participated in.

    When feedback is addressed, mark the thread as **Resolved**; it will collapse in the list and can be reopened later. Resolving a thread pauses further notifications until it is reopened.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Free regenerations">
    <Frame background="subtle">
      ![Studio free regenerations](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e9f286e5961c248a0aeca96d6f12e2e0487813935ee05aa98a1bd1ac5298bf82/assets/images/product-guides/studio/studio-free-regen.webp)
    </Frame>

    In Studio, provided you don't change the text or voice, you can regenerate a selected paragraph or section of text twice for free.

    If free regenerations are available for the selected paragraph or text, you will see **Regenerate**. If you hover over the **Regenerate** button, the number of free regenerations remaining will be displayed.

    Once your free regenerations have been used, the button will display **Generate**, and you will be charged for subsequent generations.
  </Accordion>

  <Accordion title="Auto-regeneration for bulk conversions">
    When using **Export** to generate audio for a full chapter or project, auto-regeneration automatically checks the output for volume issues, voice similarity, and mispronunciations. If any issues are detected, the tool will automatically regenerate the audio up to twice, at no extra cost.

    This feature may increase the processing time but helps ensure higher quality output for your bulk conversions.
  </Accordion>
</AccordionGroup>


# Music

> Generate and edit custom songs in any style using AI-powered music creation tools

<iframe width="100%" height="400" src="https://www.youtube.com/embed/6EtpBRcvrl4" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Eleven Music offers an end-to-end workflow for music creation. Generate songs in any style, at your desired length,
and refine every detail with intuitive editing tools. Once complete, export your track as a high-fidelity MP3 audio file,
ready for professional use.

## Guide

<Steps>
  <Step title="Create a new song">
    Describe your song using natural language prompts. Refer to our [Prompting
    Guide](/docs/overview/capabilities/music/best-practices) for best practices on style and lyrics.
  </Step>

  <Step title="Select settings">
    Choose the number of **Variants** and the **Duration**. You can select a fixed length (e.g.,
    30s, 1m) or **Auto** for a dynamically determined length. For building complex songs, a workflow
    we've seen often is to start with a short duration like **30s** and iteratively adding new
    sections as you work on the song.
  </Step>

  <Step title="Make edits">
    Refine your track in the editor. You can edit lyrics, add or remove sections, adjust section
    durations, apply style keywords, or use direct conversational prompts for granular creative
    control. You can even generate completely new variations of the exact same prompt if you want a
    different track based on the same prompt in the same music project, or a different base to work
    from.
  </Step>

  <Step title="Download and share">
    Click the **Download** button to save your high-fidelity audio file, or use the **Share** button
    to generate a link with a customizable visualizer for your track.
  </Step>
</Steps>

## What can I generate with Eleven Music?

Eleven Music is a versatile model that gives you control over many aspects of music creation. You can generate:

<AccordionGroup>
  <Accordion title="Full Songs with Vocals">
    #### Full Songs with Vocals

    Create complete tracks with AI-generated lyrics and vocals in
    multiple languages including English, Spanish, German, and Japanese. The model understands
    nuanced prompts and can generate songs in most styles or genres.
  </Accordion>

  <Accordion title="Instrumental Tracks">
    #### Instrumental Tracks

    Generate purely instrumental music across any genre, from cinematic
    scores to ambient lo-fi beats. Perfect for background music, film scores, or any project
    requiring instrumental accompaniment.
  </Accordion>

  <Accordion title="Specific Song Structures">
    #### Specific Song Structures

    Use sectional descriptions in your prompt to build songs piece by
    piece, defining the Intro, Verse, Chorus, Breakdown, and Outro. This gives you granular control
    over your song's composition and flow.
  </Accordion>

  <Accordion title="Music for Media">
    #### Music for Media

    Design custom soundtracks for videos, advertisements, games, or other media
    by describing the scene or mood. For example: "A high-intensity orchestral track for an epic
    battle scene" or "Upbeat corporate jingle for a tech startup."
  </Accordion>

  <Accordion title="Genre-Specific Music">
    #### Genre-Specific Music

    Generate highly specific styles by including detailed prompts, such as
    "Traditional Spanish flamenco with palmas, nylon guitar, and Spanish-language vocals" or "1980s
    synthwave with analog synthesizers and retro drum machines."
  </Accordion>
</AccordionGroup>

## Editing and Refinement

Once you've generated your initial track, Eleven Music provides powerful editing tools to refine every aspect
of your composition.

<AccordionGroup>
  <Accordion title="Adding and Removing Sections">
    #### Adding and Removing Sections

    **Adding a New Section:**

    * To insert a section between existing ones, hover over the section in the section view and click the
      **"+ Add Section"** icon that appears. This will add a section after the current section.
    * To add a section at the end of your track, scroll to the end of the timeline and click the **"+"** button.
    * Drag the new section in the timeline to adjust its duration.

    **Removing a Section:**

    * Hover over the section you wish to remove in the song structure view.
    * Click the delete icon (X) that appears in the corner of the section block.
  </Accordion>

  <Accordion title="Editing Lyrics and Prompts">
    #### Editing Lyrics and Prompts

    To change the lyrics or instrumental prompts of any existing section:

    * Click inside the text box for that section (e.g., Intro, Main Theme).
    * Type your new lyrics or edit the existing prompt.
    * Use bracketed descriptions like "\[energetic guitar solo]" or "\[drum fill]" for instrumental parts.
  </Accordion>

  <Accordion title="Style Control">
    #### Style Control

    For advanced control over specific musical elements:

    * Hover over the section you want to edit and click **"Edit styles of this section"**.
    * In the "Section styles" window, you can:
      * **Include styles:** Add specific musical characteristics like "gradual filter cutoff",
        "hi-hats fade out", or "long delay feedback on vocals."
      * **Exclude styles:** Prevent certain elements like "abrupt ending" or "new elements."
    * Click **Save** to apply these style rules to that specific section.
  </Accordion>

  <Accordion title="Direct Prompting">
    #### Direct Prompting

    Use the conversation interface at the bottom of the editor to make specific changes with natural language:

    * Type direct instructions like "Make the chorus more energetic" or "Add a guitar solo after the second verse."
    * This allows for creative editing beyond the structured tools.
  </Accordion>

  <Accordion title="Regenerating Changes">
    #### Regenerating Changes

    After making any edits—whether adding, deleting, or modifying sections—your changes are staged but not yet applied to the audio.

    * Your edits will **not** take effect until you click the **Generate** button.
    * Once you click **Generate**, the model creates a new version of the song incorporating all your changes.
    * Feel free to experiment with different combinations of lyrics, styles, and structures between generations.
  </Accordion>
</AccordionGroup>

## Best Practices for Prompting

The key to great results is a descriptive and detailed prompt. The more information you provide, the closer the output will be to your vision.

<AccordionGroup>
  <Accordion title="Be Specific with Genre and Style">
    #### Be Specific with Genre and Style

    Instead of generic terms like "rock music," try detailed descriptions:

    * "Energetic 1980s synth-pop with a driving drum machine beat and male vocals"
    * "Melancholic indie folk with fingerpicked acoustic guitar and ethereal female harmonies"
    * "Heavy metal with palm-muted riffs, double bass drums, and aggressive vocals"
  </Accordion>

  <Accordion title="Layer Multiple Descriptors">
    #### Layer Multiple Descriptors

    Combine mood, instrumentation, tempo, and use case for better results:

    * "A slow, melancholic piano melody over ambient synth textures, suitable for a tragic film scene"
    * "Upbeat corporate jingle with bright synthesizers, punchy drums, and an optimistic melody"
    * "Dark, atmospheric electronic track with deep bass, glitchy percussion, and haunting vocal samples"
  </Accordion>

  <Accordion title="Define Instrumentation">
    #### Define Instrumentation

    Call out specific instruments you want to hear:

    * "Upbeat funk track with a prominent slap bass line, funky rhythm guitar, and a horn section"
    * "Classical string quartet with violin, viola, and cello"
    * "Jazz ensemble with piano, upright bass, brushed drums, and tenor saxophone"
  </Accordion>

  <Accordion title="Use Include/Exclude Styles">
    #### Use Include/Exclude Styles

    Refine your output by explicitly including or excluding certain elements at the track or section level:

    * **Include:** "acoustic," "four-on-the-floor kick", "reverb-heavy vocals", "analog warmth"
    * **Exclude:** "repetitive structure", "electronic elements", "abrupt ending", "distorted vocals"
  </Accordion>

  <Accordion title="Build Section by Section">
    #### Build Section by Section

    For maximum control, start with a short generation (e.g., 30 seconds for an Intro)
    and build your song piece by piece.

    1. Generate the **Intro** and refine until satisfied.
    2. Click **"+ Add Section"** to add the next part.
    3. Specify the style and content for the new section (e.g., Verse, Chorus, Bridge).
    4. Use the conversation interface for specific instructions on each part.
    5. Build your track progressively, ensuring each section flows naturally.
  </Accordion>

  <Accordion title="Iterate and Refine">
    #### Iterate and Refine

    Don't start over if the first generation isn't perfect. Small changes can have a big impact.

    * Adjust your prompt and regenerate specific sections.
    * Use the editing tools to fine-tune individual parts.
    * Experiment with different style combinations.
  </Accordion>
</AccordionGroup>

## Use Cases & Commercial Use

Created in collaboration with artists, labels, and publishers, Eleven Music is, under certain subscriptions and conditions,
**cleared for broad commercial use**. This model allows users to move beyond stock music libraries and create bespoke audio
tailored to their specific needs.

<Note>
  For specific details on supported usage per tier, please refer to our [Music
  Terms](https://elevenlabs.io/music-terms).
</Note>

## Export and Quality

When you're satisfied with your composition, use the **Download** button to export your track.

<AccordionGroup>
  <Accordion title="Export Formats">
    #### Export Formats

    Generated audio is provided in MP3 format with professional-grade quality (44.1kHz, 128-192kbps).
    Other audio formats will be supported soon.
  </Accordion>

  <Accordion title="Quality Settings">
    #### Quality Settings

    Export quality varies by subscription tier:

    * **Free, Starter, and Creator:** Standard quality exports.
    * **Pro, Scale, Business, and Enterprise:** High-fidelity, studio-grade exports.
      All exports maintain the full dynamic range and frequency response of the original generation.
  </Accordion>

  <Accordion title="Sharing">
    #### Sharing

    Use the **Share** button to:

    * Generate a shareable link to your song.
    * Customize the visualizer that accompanies your track.
    * Share your creations with collaborators or audiences.
  </Accordion>
</AccordionGroup>

## Availability & API Access

Eleven Music is available today for all users on the ElevenLabs website. The intuitive interface makes it easy to create professional-quality music without technical expertise.

**API Access:** Public API access is coming soon. Please [reach out](https://elevenlabs.io/eleven-music-api-request) to request early access.

<Note>
  Visit our [Music Product Page](https://elevenlabs.io/music) for the latest information and to
  start creating.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="How is music generation cost calculated?">
    The cost for generating music is calculated based on your selected settings and is shown next to the Generate button. Unlike other ElevenLabs tools with fixed credit pricing, the number of credits used can vary depending on your subscription plan. This is because the cost is based on a fixed fiat price, which translates to a different number of credits for each plan.

    When using the **Auto** duration setting, you are charged based on the actual number of seconds of audio generated. Before generation, we display the price per minute for reference, but the final cost is based on the exact duration of the generated track.
  </Accordion>

  <Accordion title="How long can my generated songs be?">
    You can create everything from short clips to full-length tracks. For maximum control, you can
    start with a short duration like **30s** to create an initial section, then iteratively use the
    **"+ Add Section"** button to build out your song piece by piece, extending it to your desired
    length.

    The minimum duration of a song is 3 seconds and the maximum is 5 minutes.
  </Accordion>

  <Accordion title="Can I use generated music commercially?">
    Eleven Music is cleared for broad commercial use. See our [Music
    Terms](https://elevenlabs.io/music-terms) for specific usage details per subscription tier.
  </Accordion>

  <Accordion title="What languages are supported for vocals?">
    Eleven Music supports vocals in multiple languages including English, Spanish, German, and
    Japanese. The model can generate lyrics in these languages, or you can provide your own lyrics for
    the AI to sing.
  </Accordion>

  <Accordion title="Can I edit specific parts of my song after generation?">
    You can edit individual sections, modify lyrics, adjust durations, add or remove sections, and fine-tune
    the style of specific parts. Changes take effect when you click **Generate** to create a new version.
  </Accordion>

  <Accordion title="How do I get the best results?">
    The key is detailed, specific prompting. Include genre, mood, instrumentation, tempo, and use case in your
    descriptions. Use the Include/Exclude styles feature for fine control, and build songs section by section for
    maximum precision. See our [Prompting Guide](/docs/overview/capabilities/music/best-practices) for comprehensive tips.
  </Accordion>
</AccordionGroup>


# Dubbing

> Translate audio and video files with ElevenLabs dubbing and dubbing studio.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/RKzp4OfCgBA" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

**Dubbing** allows you to translate content across 29 languages in seconds with voice translation, speaker detection, and audio dubbing.

Automated Dubbing or Video Translation is a process for translating and replacing the original audio of a video with a new language, while preserving the unique characteristics of the original speakers' voices.

We offer two different types of Dubbing: Automatic and Studio.

**Automatic Dubbing** is the default, so let’s see the step by step for this type of dubbing.

<Frame background="subtle">
  ![Dubbing new project](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4da6343750554dcde7060e1a097fff87552439690599b1ac401bd557a89f0867/assets/images/product-guides/dubbing/dubbing-new-project.png)
</Frame>

### Step by step for Automatic Dubbing

1. Go to the Dubbing Studio in your Navigation Menu.
2. Enter the dub name and select the original and target languages.
3. Upload a video/audio file or import one via URL (YouTube, TikTok, etc.).
4. Opt for watermarking if needed.
5. Leave the Create a Dubbing Studio project box unchecked.
6. Click on the **Advanced Settings** option:
   * Choose the number of speakers and video resolution.
   * Select the specific range for dubbing if needed.
7. Click on **Create** and sit back while ElevenLabs does its magic.

**Exercise**: Dub the video found [here](https://www.youtube.com/watch?v=WnNFZt0qjD0) from English to Spanish (or a language of your choosing). Select 6 speakers and keep the watermark.

<CardGroup>
  <Card title="API reference" href="/docs/api-reference/text-to-voice">
    See the API reference for dubbing.
  </Card>

  <Card title="Example app" href="https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/dubbing">
    A Python flask example app for dubbing.
  </Card>
</CardGroup>

### Dubbing Studio Project

* This is the advanced Dubbing version, which you can access by checking the **Create a Dubbing Studio project** box. Read more about it in the [Dubbing Studio guide](/docs/creative-platform/products/dubbing/dubbing-studio).


# Dubbing Studio

> Fine-grained control over your dubs.

<CardGroup cols={1}>
  <video width="100%" height="400" controls>
    <source src="https://storage.googleapis.com/eleven-public-cdn/video/dubbing/new-dubbing-tutorial.mp4" type="video/mp4" />

    Your browser does not support the video tag.
  </video>
</CardGroup>

## Create a Dubbing Studio project

1. Check the 'Create Dubbing Studio' box when creating a dub.

<Frame background="subtle">
  ![Create Dubbing Studio Project](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c334b44ee4e91578c7be68c2bec87f88500b32ee3d79238c8719a1b102744941/assets/images/product-guides/dubbing/dubbing-studio-create.png)
</Frame>

2. Click on **Create Dub**. Once the Dubbing Studio project is created, you will be able to open it.

## Core Concepts

<AccordionGroup>
  <Accordion title="Speaker Cards">
    ## Speaker Cards

    <Frame background="subtle">
      ![Dubbing Studio Speaker Cards](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c6be1de4bd0554d29e1e8c64623d047724294b0ba4afac818c4a067f5d423465/assets/images/product-guides/dubbing/dubbing-studio-edits.gif)
    </Frame>

    Speaker cards show the original transcription and translation (if you add one) of dialogue from the source video. You can click 'Transcribe Audio' to retranscribe
    the original speech, or click the arrow to re-translate an existing transcription.

    ### Edit Transcripts and Translations

    Both transcriptions and translations can be edited freely - just click inside a speaker card and start typing to edit the text.

    ### Speaker Identification

    You can see the name of each speaker in the top left of the speaker card. To change the name of a speaker or reassign a clip to a different speaker,
    you'll need to use the Timeline.
  </Accordion>

  <Accordion title="Timeline">
    ## Timeline

    The timeline contains many important elements of Dubbing Studio, covered in more detail in different sections below:

    ### Basic navigation

    There are 3 main ways to navigate the timeline:

    1. Click and drag the cursor
    2. Horizontally scroll
    3. Input a specific timecode on the right side of the timeline

    ### Adjust clips and regenerate audio

    1. Drag the handles on the left or right side of a clip to adjust its length.
    2. Click the refresh icon to regenerate the audio for that clip.

    <Frame background="subtle">
      ![Dubbing Studio Adjust and Regenerate](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3320cc4f5d628066da8d168fcfe0d1586d8a57e618a786fd5e5839ae487642f0/assets/images/product-guides/dubbing/dubbing-studio-adjust-regenerate.gif)
    </Frame>

    ##### Dynamic vs. Fixed Generations

    NOTE: By default, all regenerations in Dubbing Studio are <i>Fixed Generations</i>, which means that the system will keep the duration of the clip fixed regardless
    of how much text it contains. This can lead to speech speeding up or slowing down significantly if you adjust the length of a clip without changing the text, or if you add/remove
    a large number of words to a clip.

    Consider a clip with the phrase 'I'm doing well.' If that clip were set to last 10 seconds and the audio were generated using Fixed Generations, the speech would sound
    slow and drawn out.

    Alternatively, you can use <i>Dynamic Generations</i> by right clicking a segment and selecting it from the options. This will attempt to adjust the
    length of the clip to the length of the text and make the audio sound more natural.

    But be careful – using Dynamic Generations could affect sync and timing in your videos. If, for example, you select Dynamic Generation for a clip with many words in it,
    and there is not enough room before the next clip for it to properly expand, the audio may not generate properly.

    <Frame background="subtle">
      ![Dubbing Studio Dynamic Generation](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/25222c5ca2adb6d17899d1949bd07b4c4b3249f59da4f08d77b9525a572e8721/assets/images/product-guides/dubbing/dubbing-studio-dynamic.gif)
    </Frame>

    ##### Stale Audio

    Stale audio refers to audio that needs to be regenerated for one of many reasons (clip length changes, settings changes, transcription/translation changes, etc). You can regenerate stale
    clips individually or click 'Generate Stale Audio' to bulk generate all stale audio clips.

    ##### Clip History

    You can right click a clip and select 'Clip History' to view previous generations and select the one that sounds best.

    ### Split and Merge clips

    1. To split a clip, move the cursor to a specific timecode and click 'Split'.
    2. To merge two clips, drag the ends of the clips together and click 'Merge.'

    <Frame background="subtle">
      ![Dubbing Studio Merge](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/44afe6659b3ea14d9baa16e735725759ced84469ed8d66a5a708f33950363a8f/assets/images/product-guides/dubbing/dubbing-studio-split-merge.gif)
    </Frame>

    As you split and merge clips, the speaker cards above the timeline will update to reflect these changes.

    ### Reassign clips to different speakers

    To reassign a clips to a different speaker, click the segment and drag it to another track.

    <Frame background="subtle">
      ![Dubbing Studio Reassign Clips](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/93fc997eba2a8a3e7ec831731cae6a20d3c55df45e5818b9629bb1dcf4d3b519/assets/images/product-guides/dubbing/dubbing-studio-reassign.gif)
    </Frame>

    ### Add additional audio tracks

    Use the action buttons at the bottom of the timeline to add new audio tracks

    <Frame background="subtle">
      ![Dubbing Studio Add Tracks](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6144bb02bb8a9da95cd4fbf76d9df479b2174e83fb8569bdeaf9b14743d19cdf/assets/images/product-guides/dubbing/dubbing-studio-add-tracks.png)
    </Frame>
  </Accordion>

  <Accordion title="Voice Settings">
    ## Voice Settings

    ### Voice Selection

    To select the voice that will be used to generate audio on a specific speaker track, click the settings cog icon on the left side of the timeline near the speaker name.

    There are 3 main types of voices to choose from in Dubbing Studio:

    1. Clip clone - this creates a unique voice clone for each clip based on the source audio for that clip
    2. Track clone - this creates a single voice clone for the whole track based on all source audio for a given speaker
    3. Other voices - you can also choose from thousands of voices available in our Voice Library, each with detailed metadata and tags to help you choose the right one

    You can also create, save, and reuse a voice from a specific clip by right clicking the clip and selecting 'Create Voice from Selection.'

    ### Setting Track vs. Clip Level Settings

    You can set voice settings at two levels:

    1. Track Level - changes will apply across all clips in the track, which can help with stability and consistency.

    2. Clip Level - changes will only apply to a specific clip. To set clip-level settings, use the panel on the right side of the timeline.
       Disable the 'inherit track settings' toggle and configure your desired settings.

    <Frame background="subtle">
      ![Dubbing Studio Voice
      Settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b4d2221711308a019b150e06634b62a9d9161ac9f51662d0aa3aaeb95e623b81/assets/images/product-guides/dubbing/dubbing-studio-clip-settings.gif)
    </Frame>
  </Accordion>

  <Accordion title="Exports">
    ## Exports

    Click 'Export' in the bottom right of Dubbing Studio to open the export menu.

    Dubbing Studio currently supports the following export formats:

    * AAC (audio)
    * MP3 (audio)
    * WAV (audio)
    * .zip of audio tracks
    * .zip of audio clips
    * AAF (timeline data)
    * SRT (subtitles/captions)
    * CSV (speaker, start\_time, end\_time, transcription, translation)

    <b>Make sure you select the correct language</b> when exporting.
  </Accordion>
</AccordionGroup>

## Additional Features

* **Voiceover Tracks:** Voiceover tracks create new Speakers. You can click and add clips on the timeline wherever you like. After creating a clip, start writing your desired text on the speaker cards above. You'll first need to translate that text, then you can press "Generate". You can also use our voice changer tool by clicking on the microphone icon on the right side of the screen to use your own voice and then change it into the selected voice.
* **SFX Tracks:** Add a SFX track, then click anywhere on that track to create a SFX clip. Similar to our independent SFX feature, simply start writing your prompt in the Speaker card above and click "Generate" to create your new SFX audio. You can lengthen or shorten SFX clips and move them freely around your timeline to fit your project - make sure to press the "stale" button if you do so.
* **Upload Audio:** This option allows you to upload a non voiced track such as sfx, music or background track. Please keep in mind that if voices are present in this track, they won't be detected so it will not be possible to translate or correct them.

## Manual Dub

In cases where you already have an accurate dubbing script prepared and want to ensure your Dubbing Studio project sticks to your
exact clips and speaker assignment, you can use the <b>Manual Dub</b> option during creation.

To create a Manual Dub, you'll need:

1. Video file
2. Background audio file
3. Foreground audio file
4. CSV where each row contains a speaker, start\_time, end\_time, transcription, and translation field

The CSV file must strictly follow the predefined format in order to be processed correctly. Please see below for samples in the three supported timecodes:

* seconds
* hours:minutes:seconds:frame
* hours:minutes:seconds,milliseconds

### Example CSV files

<CodeBlocks>
  ```csv seconds
  speaker,start_time,end_time,transcription,translation
  Adam,"0.10000","1.15000","Hello, how are you?","Hola, ¿cómo estás?"
  Adam,"1.50000","3.50000","I'm fine, thank you.","Estoy bien, gracias."

  ```

  ```csv hours:minutes:seconds:frame
  speaker,start_time,end_time,transcription,translation
  Adam,"0:00:01:01","0:00:05:01","Hello, how are you?","Hola, ¿cómo estás?"
  Adam,"0:00:06:01","0:00:10:01","I'm fine, thank you.","Estoy bien, gracias."

  ```

  ```csv hours:minutes:seconds,milliseconds
  speaker,start_time,end_time,transcription,translation
  Adam,"0:00:01,000","0:00:05,000","Hello, how are you?","Hola, ¿cómo estás?"
  Adam,"0:00:06,000","0:00:10,000","I'm fine, thank you.","Estoy bien, gracias."

  ```
</CodeBlocks>

| speaker | start\_time | end\_time   | transcription                     | translation                                  |
| ------- | ----------- | ----------- | --------------------------------- | -------------------------------------------- |
| Joe     | 0:00:00.000 | 0:00:02.000 | Hey!                              | Hallo!                                       |
| Maria   | 0:00:02.000 | 0:00:06.000 | Oh, hi, Joe. It has been a while. | Oh, hallo, Joe. Es ist schon eine Weile her. |
| Joe     | 0:00:06.000 | 0:00:11.000 | Yeah, I know. Been busy.          | Ja, ich weiß. War beschäftigt.               |
| Maria   | 0:00:11.000 | 0:00:17.000 | Yeah? What have you been up to?   | Ja? Was hast du gemacht?                     |
| Joe     | 0:00:17.000 | 0:00:23.000 | Traveling mostly.                 | Hauptsächlich gereist.                       |
| Maria   | 0:00:23.000 | 0:00:30.000 | Oh, anywhere I would know?        | Oh, irgendwo, das ich kenne?                 |
| Joe     | 0:00:30.000 | 0:00:36.000 | Spain.                            | Spanien.                                     |


# Transcripts

> Using the ElevenLabs Transcript Editor

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/48ca56e96f6cbfe0614bce01f133a8df6f3a62e0b9c26d02c8bffc415d1caf62/assets/images/product-guides/transcripts/v2-editor-landing.png" alt="Transcript Editor Product Feature" />

## Transcript Editor

<Steps>
  <Step title="Open transcript">
    In the ElevenLabs dashboard, navigate to the Speech to Text page and click any transcript to open the Transcript Editor.

    <Frame background="subtle">
      ![Open transcript](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2359a7f6f5c82bf570c68adf2d41c78916a62f81f1dfc9445532de39eb5f2292/assets/images/product-guides/speech-to-text/click-transcript.png)
    </Frame>
  </Step>

  <Step title="Edit basic details">
    You can rename your transcript in the panel on the right side of the screen.

    <Frame background="subtle">
      ![Edit details](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/db9d9ad8c65bc54a6e99b7b9ce6797308cde744f35ebdfdaa9a8a3a29f10678d/assets/images/product-guides/transcripts/v2-editor-details.gif)
    </Frame>
  </Step>

  <Step title="Edit text">
    Our transcript editor is WYSIWYG. Click anywhere in the transcript and start typing to edit the text.

    <b>Tip:</b> Use command+z to undo changes easily.

    <Frame background="subtle">
      ![Edit text](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4f877779e3c5ced07f4281d9fd4d144603b5de9dc1dee1af0cace2994b85317b/assets/images/product-guides/transcripts/v2-editor-edit-text.gif)
    </Frame>
  </Step>

  <Step title="Adjust segment start and end times">
    Drag the handles on the timeline to adjust the start and end timestamps for a segment. You can also type in exact timestamps in the panel on the right side of the screen.

    <Frame background="subtle">
      ![Adjust times](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/54b3c8b45eb021a279810f7d125bc22336f7f13bdd93e527a28e9e1eccfde592/assets/images/product-guides/transcripts/v2-editor-adjust-times.gif)
    </Frame>
  </Step>

  <Step title="Split and merge segments">
    To split a segment, click in the text where you want to split and press **Enter.**

    To merge two segments, click the 'merge segments' button. Note that two conditions must be fulfilled for a merge to be possible:

    1. Both segments must belong to the same speaker
    2. The segments must be adjacent to each other

    <Frame background="subtle">
      ![Split and merge](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/94b930ed17c519a70bc057701d39ed79e3cdc41fb2d39af581fd401e1e951ec4/assets/images/product-guides/transcripts/v2-editor-split-merge.gif)
    </Frame>
  </Step>

  <Step title="Add or remove segments">
    To add a segment, click on the 'Add Segment' icon and select a location on the timeline.

    To delete a segment, select the segment and click ‘Delete’ in the panel on the right side of the screen or press the Delete key

    <Frame background="subtle">
      ![Add/remove segments](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9db6cef9f4b4baf8f2c60e6e6280afdd11ad80aacb394dcb8906a5fbd13169a7/assets/images/product-guides/transcripts/v2-editor-add-delete.gif)
    </Frame>
  </Step>

  <Step title="Re-align words inside a segment">
    Click ‘align words’ after making changes to a segment to recompute word-level timestamps.

    <Frame background="subtle">
      ![Re-align words](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f3fb2c36a6a641bf5faa34da0af6e57ad70ba290283f09af6fabd9905c1a81dc/assets/images/product-guides/transcripts/v2-editor-realign.gif)
    </Frame>
  </Step>

  <Step title="Re-assign segments to different speakers">
    There are 2 ways to assign segments to different speakers:

    1. **Individually**: click the orb next to the speaker name for a segment, and select a new speaker from the dropdown list.
    2. **Bulk:** to reassign all segments from one speaker to another, click on the three dots (⋮) and select 'Move Segments To'. Then select the new speaker.

    <Frame background="subtle">
      ![Re-assign segments](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2f679d0d5ff2a586dbef04b98273d2cdb1bfcd44a169fb3283ff283fd5b7573c/assets/images/product-guides/transcripts/v2-editor-reassign.gif)
    </Frame>
  </Step>

  <Step title="Add or delete speakers">
    To add a speaker, click the '+' icon above the speaker tracks. To delete a speaker, click on the three dots (⋮) next to the speaker’s track and click ‘Delete.’

    **Important note**: if you delete a speaker, all of their associated segments will also be deleted.

    <Frame background="subtle">
      ![Add/delete speakers](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ccea0822dedac1b6ac693087956f8a10fb4c3bb153795ea5e1366bece125f3e8/assets/images/product-guides/transcripts/v2-editor-add-delete-speakers.gif)
    </Frame>
  </Step>

  <Step title="Reorder speaker tracks and change colors">
    Click and drag to reorder speaker tracks on the timeline. You can also change the color of a speaker track (which also applies to all its segments) by clicking the orb next to the speaker name.

    <Frame background="subtle">
      ![Reorder and color](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3bfc008392fed7ca796594d5aebb266a63b0c4f4e192e04fba8d084acc404ef0/assets/images/product-guides/transcripts/v2-editor-color-reorder.gif)
    </Frame>
  </Step>

  <Step title="Adjust playback speed">
    You can adjust the playback speed of the source media by clicking the indicator next to the play button.

    <Frame background="subtle">
      ![Playback speed](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7e585e9029ecb71342124be24a0a40d7620f0551c362460cb460307222b53b65/assets/images/product-guides/transcripts/v2-editor-speed.png)
    </Frame>
  </Step>

  <Step title="Export transcript">
    Click the export button in the top right of the screen and select one of the transcript export formats:

    * Plain text
    * JSON
    * HTML
    * SRT
    * VTT

    <Frame background="subtle">
      ![Exports](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5ba313e9580586330fe51c8ef12f3dc6babc734e4503bf6d1c7bee3d2a4b8b0c/assets/images/product-guides/transcripts/v2-editor-exports.png)
    </Frame>
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Does the transcript editor also support subtitles?">
    Yes – you can add subtitles by clicking the '+' next to 'Subtitles' in the panel on the right
    side of the screen.

    To learn more about editing subtitles, please see our [Subtitle guide](/docs/creative-platform/products/subtitles).
  </Accordion>

  <Accordion title="Can someone review my transcript to make sure it's accurate?">
    Yes – our Productions team offers human transcription services from \$2.00 per minute of audio. What you get from us:

    * Expert review by a native speaker
    * Optional 'Verbatim Mode' for maximum coverage of non-verbal sounds (\[cough], \[sigh], etc.) and other environmental sounds and audio events (\[dog barking], \[car horn], etc.)

    For more information please see the 'Productions' section of your ElevenLabs account (currently in beta and available to select users) or contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).
  </Accordion>
</AccordionGroup>


# Subtitles

> Using the ElevenLabs Subtitle Editor

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c27d860735dc78c9c1c8962fbf0b9ec190a08a4ed2a324719f626fc0f7e60f36/assets/images/product-guides/subtitles/subtitles-landing.png" alt="Subtitle Editor Product Feature" />

## Subtitle Editor

<Steps>
  <Step title="Open transcript editor">
    You can use the subtitling mode of our transcript editor to edit your subtitles. Navigate to the Speech to Text page of your ElevenLabs account and click any transcript to get started.

    <Frame background="subtle">
      ![Open transcript](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2359a7f6f5c82bf570c68adf2d41c78916a62f81f1dfc9445532de39eb5f2292/assets/images/product-guides/speech-to-text/click-transcript.png)
    </Frame>
  </Step>

  <Step title="Edit basic details">
    You can rename your subtitles in the panel on the right side of the screen.

    <Frame background="subtle">
      ![Edit details](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/db9d9ad8c65bc54a6e99b7b9ce6797308cde744f35ebdfdaa9a8a3a29f10678d/assets/images/product-guides/transcripts/v2-editor-details.gif)
    </Frame>
  </Step>

  <Step title="Add subtitles">
    If you didn't add subtitles when creating the transcript, you can do so by clicking the "+" next to "Subtitles" in the panel on the right side of the screen.
    You can switch between transcription and subtitling mode at any time using the tabs at the top of the editor.

    <b>Tip:</b> you can also add subtitles during the transcript creation process by enabling the 'Include subtitles' toggle.

    <Frame background="subtle">
      ![Add subtitles](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d129c29b30a9add87a984eb9aa861745be2d0701bf1734a06e805b43872f591c/assets/images/product-guides/subtitles/subtitles-add.gif)
    </Frame>

    <Frame background="subtle">
      ![Add subtitles](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/239e34f933d4464e5887458985117ab8dad9cbb5e2a37acb6beecd96e8c096ca/assets/images/product-guides/subtitles/subtitles-dialog.png)
    </Frame>
  </Step>

  <Step title="Edit rules/constraints">
    Our subtitle editor uses red and green colors to give you real-time feedback on whether your subtitles respect formatting rules like characters per line, lines on screen, and cue length.

    To edit these rules, click the three dots next to 'Subtitles' in the panel on the right side of the screen and select 'Edit rules'

    <Frame background="subtle">
      ![Edit rules](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/675daf87d4ca043271f57c3c584b0eb6ddb1ff13e80ee5e55c39997aaa059fea/assets/images/product-guides/subtitles/subtitles-warning.png)
    </Frame>

    <Frame background="subtle">
      ![Edit rules](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/208f20af0e907858ab03896fd0ba40276ec402ee9ec7094b3ee60c8dcdc67012/assets/images/product-guides/subtitles/subtitles-rules.png)
    </Frame>
  </Step>

  <Step title="Edit text">
    Our subtitle editor is WYSIWYG. Click anywhere and start typing to edit the text.

    <b>Tip:</b> Use command+z to undo changes easily.

    <Frame background="subtle">
      ![Edit text](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b17224c439b82f5824b3d0abfc9d8634155bcd4d4bbb3726faec2dda8af9520/assets/images/product-guides/subtitles/subtitles-edit-text.gif)
    </Frame>
  </Step>

  <Step title="Adjust cue start and end times">
    Drag the handles on the timeline to adjust the start and end timestamps for a cue. You can also type in exact timestamps in the panel on the right side of the screen.

    <b>Important:</b> the transcript and subtitles for a video are completely separate from each other. Changes you make to subtitles (e.g. changing cue start/end times, adding/removing words, etc.) do NOT affect the transcription, and vice versa.

    <Frame background="subtle">
      ![Adjust times](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ab1595d83ebc540738f29b079bac0e137bb15719f8e9840fbfc54373f6929f74/assets/images/product-guides/subtitles/subtitles-adjust-times.gif)
    </Frame>
  </Step>

  <Step title="Split and merge cues">
    To split a cue, click in the text where you want to split and press **Enter.**

    To merge two cues, click the 'merge cues' button.

    <Frame background="subtle">
      ![Split and merge](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5de3d80fd08a0ca5599dbea713012a4ca125f641d8e70b4c822b8bc2ceb41381/assets/images/product-guides/subtitles/subtitles-split-merge.gif)
    </Frame>
  </Step>

  <Step title="Add or remove cues">
    To add a cue, click 'Add cue' and select a location on the timeline.

    To delete a cue, select the cue and click ‘Delete’ in the panel on the right side of the screen, or press the Delete key.

    <Frame background="subtle">
      ![Add/remove segments](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5f5408ba7d6410a5f1052811c71e841449e6a69de0875f3335950e9204a67c20/assets/images/product-guides/subtitles/subtitles-add-delete.gif)
    </Frame>
  </Step>

  <Step title="Adjust playback speed">
    You can adjust the playback speed of the source media by clicking the indicator next to the play button.

    <Frame background="subtle">
      ![Playback speed](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7e585e9029ecb71342124be24a0a40d7620f0551c362460cb460307222b53b65/assets/images/product-guides/transcripts/v2-editor-speed.png)
    </Frame>
  </Step>

  <Step title="Export subtitles">
    Click the export button in the top right of the screen and select one of the subtitle export formats:

    * SRT
    * VTT

    <Frame background="subtle">
      ![Exports](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5ba313e9580586330fe51c8ef12f3dc6babc734e4503bf6d1c7bee3d2a4b8b0c/assets/images/product-guides/transcripts/v2-editor-exports.png)
    </Frame>
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Are transcripts and subtitles different?">
    Yes – subtitles have specific formatting rules and requirements that do not apply to transcripts.

    Below is a summary of some (but not all) of the major differences between the two:

    | Feature                        | Transcripts | Subtitles                                                        |
    | ------------------------------ | ----------- | ---------------------------------------------------------------- |
    | Word-level timestamps          | Yes         | No - only start/end times of cues                                |
    | Speaker names/labels           | Yes         | No                                                               |
    | Constraints                    | No          | Yes - characters per line, lines on screen at once, cue duration |
    | Overlapping segments supported | Yes         | No                                                               |

    For more information about transcripts, please see our [Transcripts guide](/docs/creative-platform/products/transcripts).
  </Accordion>

  <Accordion title="Do changes to subtitles affect the transcript too?">
    No – transcripts and subtitles are completely separate from each other in our editor. That means that changes you make to one will NOT affect the other.
  </Accordion>

  <Accordion title="Can ElevenLabs help me with my subtitles?">
    Yes – our Productions team offers human subtitling services from \$2.20 per minute. What you get from us:

    * A subtitling expert edits your subtitles to ensure they adhere to all formatting rules and requirements
    * If you choose, our language teams translate your subtitles into different languages

    For more information please see the 'Productions' section of your ElevenLabs account (currently in beta and available to select users) or contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).
  </Accordion>
</AccordionGroup>


# Voice Library

> A guide on how to use voices from the Voice Library.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6279d167562a3c4d9e6b93263ec8dfe4f969f713a0543a7bdf68ae2140c2f3ae/assets/images/product-guides/voices/voices-voice-library.webp" alt="Voice Library" />

## Overview

The [Voice Library](https://elevenlabs.io/app/voice-library) is a marketplace where our community can share Professional Voice Clones and earn rewards when others use them. Currently, only Professional Voice Clones can be shared. Instant Voice Clones and voices created with Voice Design are not shareable.

To access the Voice Library, click **Voices** in the sidebar and select **Explore**.

<Warning>
  The voice library is not available via the API to free tier users.
</Warning>

### Finding voices

You can browse the Voice Library in several ways:

#### Handpicked Collections

Our Handpicked Collections highlight top voices across use cases, genres, and languages. These collections are updated regularly to include new standout voices.

#### Search

Use the search bar to find voices by name, keyword, or voice ID. You can also search by uploading or dragging and dropping an audio file. This will help you find the original voice, if available, along with similar voices.

#### Sort options

You can sort voices by:

* Trending: voices ranked by popularity
* Latest: newly added voices
* Most users
* Character usage

#### Filters

Use filters to refine your search:

<AccordionGroup>
  <Accordion title="Language">
    ##### Language

    The language filter returns voices that have been trained on a specific language. While all voices can be used with any supported language, voices tagged with a specific language will perform best in that language. Some voices have been assessed as performing well in multiple languages, and these voices will also be returned when you search for a specific language.
  </Accordion>

  <Accordion title="Accent">
    ##### Accent

    When you select a language, the Accent filter will also become available, allowing you to filter for specific accents.
  </Accordion>

  <Accordion title="Category">
    ##### Category

    Filter voices by their suggested use case:

    * Conversational
    * Narration
    * Characters
    * Social Media
    * Educational
    * Advertisement
    * Entertainment
  </Accordion>

  <Accordion title="Gender">
    ##### Gender

    * Male
    * Female
    * Neutral
  </Accordion>

  <Accordion title="Age">
    ##### Age

    * Young
    * Middle Aged
    * Old
  </Accordion>

  <Accordion title="Notice period">
    ##### Notice period

    Some voices have a notice period. This is how long you'll continue to have access to the voice if the voice owner decides to remove it from the Voice Library. If the voice's owner stops sharing their voice, you'll receive advance notice through email and in-app notifications. These notifications specify when the voice will become unavailable and recommend similar voices from the Voice Library. If the owner of a voice without a notice period decides to stop sharing their voice, you'll lose access to the voice immediately.

    This filter allows you to only return voices that have a notice period, and search for voices with a specific notice period. The maximum notice period is 2 years.
  </Accordion>

  <Accordion title="Live Moderation enabled">
    ##### Live Moderation enabled

    Some voices have Live Moderation enabled. This is indicated with a label with a shield icon. When you generate using a voice with Live Moderation enabled, we use tools to check whether the text being generated belongs to a number of prohibited categories. This may introduce extra latency when using the voice.

    This filter allows you to exclude voices that have Live Moderation enabled.
  </Accordion>

  <Accordion title="Quality">
    ##### Quality

    Filter voices by their quality level:

    * **Any**: All voices regardless of quality assessment
    * **High-Quality**: Voices that have been recorded with proper equipment, mixed well, and tested to be free from most audio problems such as reverb/echo, distortion, or other artifacts. These voices exhibit an overall professional-sounding tone and are reviewed by our QA testers.
  </Accordion>
</AccordionGroup>

### Using voices from the Voice Library

To use a voice from the Voice Library, you'll need to add it to My Voices. To do this, click the **+** button.

A pop-up will appear which will give you more information about the voice. You can choose to add the voice to an existing personal collection, create a new collection, or add the voice to My Voices without including it in a collection. To confirm, click **Add voice**. This will save it to My Voices using the default name for the voice.

Voices you've added to My Voices will become available for selection in all voice selection menus. You can also use a voice directly from My Voices by clicking the **T** button, which will open Text to Speech with the voice selected.

### My Voices

You can find all the voices you've created yourself, as well as voices you've saved from the Voice Library, in **My Voices**.

You will see the following information about each voice:

* the language it was trained on.
* the category, for example, "Narration".
* how long the notice period is, if the voice has one.

The voice type is indicated by an icon:

* Yellow tick: Professional Voice Clone.
* Black tick: High Quality Professional Voice Clone.
* Lightning icon: Instant Voice Clone.
* || icon: ElevenLabs Default voice.
* No icon: voice created with Voice Design.

#### More actions

Click **More actions** (three dots) to:

* Copy voice ID: copies the voice ID to your clipboard.
* Edit voice: allows you to change the name and description of the voice. These changes are only visible to you.
* Share voice: generates a link which you can share with others. When they use the link, the voice will be added to My Voices for their account.
* View history: view your previous Text to Speech generations using this voice.
* Delete voice: deleting voices is permanent and you will be asked to confirm the deletion.

#### Collections

To help organize voices you've saved, you can create your own collections and add voices to them.

To create a new collection, click **Collections** and select **Create collection**. Give your new collection a name, and choose from the available icons.

To add individual voices to a collection, click **More actions** (three dots) and select **Add to collection**. You can choose to add the voice to an existing collection, or create a new one.

#### Select multiple voices

You can **Shift + Click** to select multiple voices at once.

#### Drag and drop voices

Both individual voices and multiple voice selections can also be dragged **Collections** and added to an existing collection, or deleted by dragging to the **trash can** icon.

### Sharing a Professional Voice Clone:

<Steps>
  <Step>
    In [My Voices](https://elevenlabs.io/app/voice-lab) find your voice and click **More actions**
    (three dots), then select **Share voice**.
  </Step>

  <Step>
    In the pop-up, enable the 

    **Sharing**

     toggle.
  </Step>

  <Step>
    For private sharing, copy the sharing link. This will allow other users to save your voice to their account.

    You can restrict access to specific users by adding emails to the **Allowlist**. If this is left blank, all users with the link will be able to access your voice.
  </Step>

  <Step>
    To share publicly, enable **Publish to the Voice Library**. This doesn’t make your voice automatically discoverable.

    <Frame background="subtle">
      ![Voice sharing overview](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/60fd4b21d2e8bba5e749edb24ec545d5990907ac6da7cbc0967bf08f7c2e0ef9/assets/images/product-guides/voices/voice-sharing.webp)
    </Frame>
  </Step>

  <Step>
    Before proceeding with the sharing process, you'll have a number of options including setting a notice period and enabling Live Moderation. Please see the [Voice Library Addendum](https://elevenlabs.io/vla) to our [Terms of Service](https://elevenlabs.io/terms-of-use) for more information about these options.

    You also have the option to select a custom voice preview. Any generations you've made of 70-150 characters will be available to select. If you don't see any options in the selection menu, there are no eligible generations available.

    <Frame background="subtle">
      ![Voice sharing options](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/95a98e53782fae49fb01c403fe998b87944b247495f2ef257512652b7588d52d/assets/images/product-guides/voices/voice-sharing-options.webp)
    </Frame>
  </Step>

  <Step>
    Enter a name and description for your voice.
    Make sure the name you give your voice follows our **naming guidelines**:

    <Accordion title="Naming guidelines">
      #### Naming guidelines

      * The naming pattern should be a one-word name followed by a 2-4 word description, separated by a hyphen (-).

      * Your name should NOT include the following:

        * Names of public individuals or entities (company names, band names, influencers or famous people, etc).
        * Social handles (Twitter, Instagram, you name it, etc).
        * ALL CAPS WORDS.
        * Emojis and any other non-letter characters.
        * Explicit or harmful words.
        * The word “voice”.

      * Some examples of names following our guidelines:
        * Anna - calm and kind
        * Robert - friendly grandpa
        * Steve - wise teacher
        * Harmony - soothing serenader
        * Jasper - jovial storyteller
        * Maya - confident narrator
    </Accordion>
  </Step>

  <Step>
    Set labels (language, accent, gender, age, use case, tone, and style) to help others find your
    voice.
  </Step>

  <Step>
    Review and accept the [Voice Library Addendum](https://elevenlabs.io/vla) to our [Terms of
    Service](https://elevenlabs.io/terms-of-use) and provide the required consents and confirmations.
    Please do this carefully and ensure you fully understand our service before sharing. If you have
    any questions at this stage, you can reach out to us at [legal@elevenlabs.io](mailto:legal@elevenlabs.io).
  </Step>

  <Step>
    After submission, your voice will be reviewed by our team. If minor adjustments are needed, we may make these for you. Your request to share your voice may be declined if it doesn't meet our guidelines, and repeated uploads that consistently violate our guidelines may lead to restrictions on uploading and sharing voices.

    We currently do not have an estimate for the review time, as it depends on the queue.
  </Step>
</Steps>


# Voice Cloning

> Learn how to clone your voice to using our best-in-class models.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/AiRksVoiUAI" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

When cloning a voice, there are two main options: Instant Voice Cloning (IVC) and Professional Voice Cloning (PVC). IVC is a quick and easy way to clone your voice, while PVC is a more accurate and customizable option.

## Instant Voice Cloning

<Frame background="subtle">
  ![Instant voice
  cloning](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/12c4c05064106f5a8e6c57cfbb00e82333d3fada90eb50dccb9df6d0e128bcba/assets/images/product-guides/voices/voice-cloning/voices-ivc-creation.jpg)
</Frame>

IVC allows you to create voice clones from shorter samples near instantaneously. Creating an instant voice clone does not train or create a custom AI model. Instead, it relies on prior knowledge from training data to make an educated guess rather than training on the exact voice. This works extremely well for a lot of voices.

However, the biggest limitation of IVC is if you are trying to clone a very unique voice with a very unique accent where the AI might not have heard a similar voices before during training. In such cases, creating a custom model with explicit training using PVC might be the best option.

## Professional Voice Cloning

<Frame background="subtle">
  ![Professional voice
  cloning](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a1c5d38f8f6a8907364450655f63936aa7c60df60bde55c513dfd745eef3b997/assets/images/product-guides/voices/voice-cloning/voices-pvc-creation.jpg)
</Frame>

A PVC is a special feature that is available to our Creator+ plans. PVC allows you to train a hyper-realistic model of a voice. This is achieved by training a dedicated model on a large set of voice data to produce a model that’s indistinguishable from the original voice.

Since the custom models require fine-tuning and training, it will take a bit longer to train these PVCs compared to an IVC. Giving an estimate is challenging as it depends on the number of people in the queue before you and a few other factors.

Here are the current estimates for PVC:

* **English:** \~3 hours
* **Multilingual:** \~6 hours

## Beginner's guide to audio recording

If you're new to audio recording, here are some tips to help you get started.

### Recording location

When recording audio, choose a suitable location and set up to minimize room echo/reverb.
So, we want to "deaden" the room as much as possible. This is precisely what a vocal booth that is acoustically treated made for, and if you do not have a vocal booth readily available, you can experiment with some ideas for a DIY vocal booth, “blanket fort”, or closet.

Here are a few YouTube examples of DIY acoustics ideas:

* [I made a vocal booth for \$0.00!](https://www.youtube.com/watch?v=j4wJMDUuHSM)
* [How to Record GOOD Vocals in a BAD Room](https://www.youtube.com/watch?v=TsxdHtu-OpU)
* [The 5 BEST Vocal Home Recording TIPS!](https://www.youtube.com/watch?v=K96mw2QBz34)

### Microphone, pop-filter, and audio interface

A good microphone is crucial. Microphones can range from \$100 to \$10,000, but a professional XLR microphone costing \$150 to \$300 is sufficient for most voiceover work.

For an affordable yet high-quality setup for voiceover work, consider a **Focusrite** interface paired with an **Audio-Technica AT2020** or **Rode NT1 microphone**. This setup, costing between \$300 to \$500, offers high-quality recording suitable for professional use, with minimal self-noise for clean results.

Please ensure that you have a proper **pop-filter** in front of the microphone when recording to avoid plosives as well as breaths and air hitting the diaphragm/microphone directly, as it will sound poor and will also cause issues with the cloning process.

### Digital Audio Workstation (DAW)

There are many different recording solutions out there that all accomplish the same thing: recording audio. However, they are not all created equally. As long as they can record WAV files at 44.1kHz or 48kHz with a bitrate of at least 24 bits, they should be fine. You don't need any fancy post-processing, plugins, denoisers, or anything because we want to keep audio recording simple.

If you want a recommendation, we would suggest something like **REAPER**, which is a fantastic DAW with a tremendous amount of flexibility. It is the industry standard for a lot of audio work. Another good free option is **Audacity**.

Maintain optimal recording levels (not too loud or too quiet) to avoid digital distortion and excessive noise. Aim for peaks of -6 dB to -3 dB and an average loudness of -18 dB for voiceover work, ensuring clarity while minimizing the noise floor. Monitor closely and adjust levels as needed for the best results based on the project and recording environment.

### Positioning

One helpful guideline to follow is to maintain a distance of about two fists away from the microphone, which is approximately 20cm (7-8 in), with a pop filter placed between you and the microphone. Some people prefer to position the pop filter all the way back so that they can press it up right against it. This helps them maintain a consistent distance from the microphone more easily.

Another common technique to avoid directly breathing into the microphone or causing plosive sounds is to speak at an angle. Speaking at an angle ensures that exhaled air is less likely to hit the microphone directly and, instead, passes by it.

### Performance

The performance you give is one of the most crucial aspects of this entire recording session. The AI will try to clone everything about your voice to the best of its ability, which is very high. This means that it will attempt to replicate your cadence, tonality, performance style, the length of your pauses, whether you stutter, take deep breaths, sound breathy, or use a lot of "uhms" and "ahs" – it can even replicate those. Therefore, what we want in the audio file is precisely the performance and voice that we want to clone, nothing less and nothing more. That is also why it's quite important to find a script that you can read that fits the tonality we are aiming for.

When recording for AI, it is very important to be consistent. if you are recording a voice either keep it very animated throughout or keep it very subdued throughout you can't mix and match or the AI can become unstable because it doesn't know what part of the voice to clone. same if you're doing an accent keep the same accent throughout the recording. Consistency is key to a proper clone!


# Instant Voice Cloning

> Learn how to clone your voice instantly using our best-in-class models.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e84acf92bc62eaf73b48f3f8c1c6b3409cf9913c6f5dd196c0dc27f431678c9d/assets/images/product-guides/voices/voice-cloning/voice-cloning-product-feature.jpg" alt="Voice cloning product feature" />

## Creating an Instant Voice Clone

When cloning a voice, it's important to consider what the AI has been trained on: which languages and what type of dataset. You can find more information about which languages each model has been trained on in our [help center](https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them).

<Info>
  Read more about each individual model and their strengths in the [Models
  page](/docs/overview/models)).
</Info>

## Guide

<Warning>
  If you are unsure about what is permissible from a legal standpoint, please consult the [Terms of
  Service](https://elevenlabs.io/terms-of-use) and our [AI Safety
  information](https://elevenlabs.io/safety) for more information.
</Warning>

<Steps>
  ### Navigate to the Instant Voice Cloning page

  In the ElevenLabs dashboard, select the "Voices" section on the left, then click "Add a new voice".

  From the modal, select "Instant Voice Clone".

  ### Upload or record your audio

  Follow the on-screen instructions to upload or record your audio.

  ### Confirm voice details

  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b3b4b3b8361ca372638c9c315e69588dcc44520bfaa00a3455720d963894d8ed/assets/images/product-guides/voices/voice-cloning/voice-cloning-ivc-modal.jpg" alt="Voice cloning IVC modal" />

  Name and label your voice clone, confirm that you have the right and consent to clone the voice, then click "Save voice".

  ### Use your voice clone

  Under the "Voices" section in the dashboard, select the "Personal" tab, then click on your voice clone to begin using it.
</Steps>

## Best practices

<AccordionGroup>
  <Accordion title="Record at least 1 minute of audio">
    #### Record at least 1 minute of audio

    Avoid recording more than 3 minutes, this will yield little improvement and can, in some cases, even be detrimental to the clone.

    How the audio was recorded is more important than the total length (total runtime) of the samples. The number of samples you use doesn't matter; it is the total combined length (total runtime) that is the important part.

    Approximately 1-2 minutes of clear audio without any reverb, artifacts, or background noise of any kind is recommended. When we speak of "audio or recording quality," we do not mean the codec, such as MP3 or WAV; we mean how the audio was captured. However, regarding audio codecs, using MP3 at 128 kbps and above is advised. Higher bitrates don't have a significant impact on the quality of the clone.
  </Accordion>

  <Accordion title="Keep the audio consistent">
    #### Keep the audio consistent

    The AI will attempt to mimic everything it hears in the audio. This includes the speed of the person talking, the inflections, the accent, tonality, breathing pattern and strength, as well as noise and mouth clicks. Even noise and artefacts which can confuse it are factored in.

    Ensure that the voice maintains a consistent tone throughout, with a consistent performance. Also, make sure that the audio quality of the voice remains consistent across all the samples. Even if you only use a single sample, ensure that it remains consistent throughout the full sample. Feeding the AI audio that is very dynamic, meaning wide fluctuations in pitch and volume, will yield less predictable results.
  </Accordion>

  <Accordion title="Replicate your performance">
    #### Replicate your performance

    Another important thing to keep in mind is that the AI will try to replicate the performance of the voice you provide. If you talk in a slow, monotone voice without much emotion, that is what the AI will mimic. On the other hand, if you talk quickly with much emotion, that is what the AI will try to replicate.

    It is crucial that the voice remains consistent throughout all the samples, not only in tone but also in performance. If there is too much variance, it might confuse the AI, leading to more varied output between generations.
  </Accordion>

  <Accordion title="Find a good balance for the volume">
    #### Find a good balance for the volume

    Find a good balance for the volume so the audio is neither too quiet nor too loud. The ideal would be between -23 dB and -18 dB RMS with a true peak of -3 dB.
  </Accordion>
</AccordionGroup>


# Professional Voice Cloning

> Learn how to clone your voice professionally using our best-in-class models.

## Creating a Professional Voice Clone

When cloning a voice, it's important to consider what the AI has been trained on: which languages and what type of dataset. You can find more information about which languages each model has been trained on in our [help center](https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them).

<Info>
  Read more about each individual model and their strengths in the [Models
  page](/docs/overview/models)).
</Info>

## Guide

<Warning>
  If you are unsure about what is permissible from a legal standpoint, please consult the [Terms of
  Service](https://elevenlabs.io/terms-of-use) and our [AI Safety
  information](https://elevenlabs.io/safety) for more information.
</Warning>

<Steps>
  ### Navigate to the Professional Voice Cloning page

  In the ElevenLabs dashboard, select the **Voices** section on the left, then click **Add a new voice**.

  From the pop-up, select **Professional Voice Clone**.

  ### Upload your audio

  <Frame background="subtle">
    ![Create a new Professional Voice Clone](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/84134ac62c71531ac93d090030d9651bf428dc90802c17b33ad924973b6560c2/assets/images/product-guides/voices/voice-cloning/voice-pvc-creation.webp)
  </Frame>

  Upload your audio samples by clicking **Upload samples**.

  If you don't already have pre-recorded training audio, you can also record directly into the interface by selecting **Record yourself**. We've included sample scripts for narrative, conversational and advertising purposes. You can also upload your own script.

  ### Check the feedback on sample length

  Once your audio has been uploaded, you will see feedback on the length of your samples. For the best results, we recommend uploading at least an hour of training audio, and ideally as close to three hours as possible.

  <Frame background="subtle">
    ![Create a new Professional Voice Clone](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/868803a15dac167dc8b97930436273e7196314e7a66a5db95ef2c16e7806c753/assets/images/product-guides/voices/voice-cloning/voice-pvc-creation-samples.webp)
  </Frame>

  ### Process your audio

  Once your audio samples have been uploaded, you can process them to improve the quality. You can remove any background noise, and you can also separate out different speakers, if your audio includes more than one speaker. To access these options, click the **Audio settings** button next to the clip you want to process.

  <Frame background="subtle">
    ![Create a new Professional Voice Clone](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2ad9fdf1aff0635cdf884d77da4dc6be7d77e7596601ebde4cb0bf50ecc80e37/assets/images/product-guides/voices/voice-cloning/voice-pvc-creation-settings.webp)
  </Frame>

  ### Verify your voice

  Once everything is recorded and uploaded, you will be asked to verify your voice. To ensure a smooth experience, please try to verify your voice using the same or similar equipment used to record the samples and in a tone and delivery that is similar to those present in the samples. If you do not have access to the same equipment, try verifying the best you can. If it fails, you can either wait 24 hours to try verification again, or reach out to support for help.

  ### Wait for your voice to complete fine tuning

  Before you can use your voice, it needs to complete the fine tuning process. You can check the status of your voice in My Voices while it's processing. You'll be notified when it's ready to use.

  ### Use your voice clone

  Under the **Voices** section in the dashboard, select the **Personal** tab, then click **Use** next to your voice clone to begin using it.
</Steps>

There are a few things to be mindful of before you start uploading your samples, and some steps that you need to take to ensure the best possible results.

<Steps>
  ### Record high quality audio

  Professional Voice Cloning is highly accurate in cloning the samples used for its training. It will create a near-perfect clone of what it hears, including all the intricacies and characteristics of that voice, but also including any artifacts and unwanted audio present in the samples. This means that if you upload low-quality samples with background noise, room reverb/echo, or any other type of unwanted sounds like music or multiple people speaking, the AI will try to replicate all of these elements in the clone as well.

  ### Ensure there's only a single speaking voice

  Make sure there's only a single speaking voice throughout the audio, as more than one speaker or excessive noise or anything of the above can confuse the AI. This confusion can result in the AI being unable to discern which voice to clone or misinterpreting what the voice actually sounds like because it is being masked by other sounds, leading to a less-than-optimal clone.

  ### Provide enough material

  Make sure you have enough material to clone the voice properly. The bare minimum we recommend is 30 minutes of audio, but for the optimal result and the most accurate clone, we recommend closer to 2-3 hours of audio. The more audio provided the better the quality of the resulting clone.

  ### Keep the style consistent

  The speaking style in the samples you provide will be replicated in the output, so depending on what delivery you are looking for, the training data should correspond to that style (e.g. if you are looking to voice an audiobook with a clone of your voice, the audio you submit for training should be a recording of you reading a book in the tone of voice you want to use). It is better to just include one style in the uploaded samples for consistencies sake.

  ### Use samples speaking the language you want the PVC to be used for

  It is best to use samples speaking where you are speaking the language that the PVC will mainly be used for. Of course, the AI can speak any language that we currently support. However, it is worth noting that if the voice itself is not native to the language you want the AI to speak - meaning you cloned a voice speaking a different language - it might have an accent from the original language and might mispronounce words and inflections. For instance, if you clone a voice speaking English and then want it to speak Spanish, it will very likely have an English accent when speaking Spanish. We only support cloning samples recorded in one of our supported languages, and the application will reject your sample if it is recorded in an unsupported language.
</Steps>

See the examples below for what to expect from a good and bad recording.

<iframe width="100%" height={90} frameBorder="no" scrolling="no" src={`https://elevenlabs.io/player/index.html?title=Good%20example&small=true&preview=true&audioSrc=https%3A%2F%2Fstorage.googleapis.com%2Feleven-public-cdn%2Faudio%2Fdocs%2Fgood_example.wav`} />

<iframe width="100%" height={90} frameBorder="no" scrolling="no" src={`https://elevenlabs.io/player/index.html?title=Bad%20example&small=true&preview=true&audioSrc=https%3A%2F%2Fstorage.googleapis.com%2Feleven-public-cdn%2Faudio%2Fdocs%2Fbad_example.wav`} />

For now, we only allow you to clone your own voice. You will be asked to go through a verification process before submitting your fine-tuning request.

## Tips and suggestions

<AccordionGroup>
  <Accordion title="Professional Recording Equipment">
    #### Professional Recording Equipment

    Use high-quality recording equipment for optimal results as the AI will clone everything about the audio. High-quality input = high-quality output. Any microphone will work, but an XLR mic going into a dedicated audio interface would be our recommendation. A few general recommendations on low-end would be something like an Audio Technica AT2020 or a Rode NT1 going into a Focusrite interface or similar.
  </Accordion>

  <Accordion title="Use a Pop-Filter">
    #### Use a Pop-Filter

    Use a Pop-Filter when recording. This will minimize plosives when recording.
  </Accordion>

  <Accordion title="Microphone Distance">
    #### Microphone Distance

    Position yourself at the right distance from the microphone - approximately two fists away from the mic is recommended, but it also depends on what type of recording you want.
  </Accordion>

  <Accordion title="Noise-Free Recording">
    #### Noise-Free Recording

    Ensure that the audio input doesn't have any interference, like background music or noise. The AI cloning works best with clean, uncluttered audio.
  </Accordion>

  <Accordion title="Room Acoustics">
    #### Room Acoustics

    Preferably, record in an acoustically-treated room. This reduces unwanted echoes and background noises, leading to clearer audio input for the AI. You can make something temporary using a thick duvet or quilt to dampen the recording space.
  </Accordion>

  <Accordion title="Audio Pre-processing">
    #### Audio Pre-processing

    Consider editing your audio beforehand if you're aiming for a specific sound you want the AI to output. For instance, if you want a polished podcast-like output, pre-process your audio to match that quality, or if you have long pauses or many "uhm"s and "ahm"s between words as the AI will mimic those as well.
  </Accordion>

  <Accordion title="Volume Control">
    #### Volume Control

    Maintain a consistent volume that's loud enough to be clear but not so loud that it causes distortion. The goal is to achieve a balanced and steady audio level. The ideal would be between -23dB and -18dB RMS with a true peak of -3dB.
  </Accordion>

  <Accordion title="Sufficient Audio Length">
    #### Sufficient Audio Length

    Provide at least 30 minutes of high-quality audio that follows the above guidelines for best results - preferably closer to 2+ hours of audio. The more quality data you can feed into the AI, the better the voice clone will be. The number of samples is irrelevant; the total runtime is what matters. However, if you plan to upload multiple hours of audio, it is better to split it into multiple \~30-minute samples. This makes it easier to upload.
  </Accordion>
</AccordionGroup>


# Voice design

> A guide on how to craft voices from a text prompt.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/_cEcV96wQ1k" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1125280670aac11f82425cb9e04ccba451fb85ac046cff42203b867a82340f43/assets/images/product-guides/voices/voices-voice-design.png" alt="Voice design" />

## Overview

Voice Design helps creators fill the gaps when the exact voice they are looking for isn't available in the [Voice Library](https://elevenlabs.io/app/voice-library). If you can't find a suitable voice for your project, you can create one. Voice Design is best for quick exploration and iteration, and output quality can vary depending on your prompt and use case. If you need the most consistent, production-ready quality, [Professional Voice Clones (PVC)](/docs/creative-platform/voices/voice-cloning) are currently the highest quality voices on our platform - so if there is a PVC available in our library that fits your needs, we recommend using it instead.

You can find Voice Design by heading to Voices -> My Voices -> Add a new voice -> Voice Design in the [ElevenLabs app](https://elevenlabs.io/app/voice-lab?create=true\&creationType=voiceDesign) or via the [API](/docs/api-reference/text-to-voice/design).

When you hit generate, we'll generate three voice options for you. The only charge for using voice design is the number of credits to generate your preview text, which you are only charged once even though we are generating three samples for you. You can see the number of characters that will be deducted in the "Text to preview" text box.

After generating, you'll have the option to select and save one of the generations, which will take up one of your voice slots.

<CardGroup>
  <Card title="API reference" href="/docs/api-reference/text-to-voice">
    See the API reference for Voice Design
  </Card>

  <Card title="Example app" href="https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-voice/x-to-voice">
    A Next.js example app for Voice Design
  </Card>
</CardGroup>

## Prompting guide

The prompt is the foundation of your voice. It tells the model what kind of voice you’re trying to create — everything from the accent and character-type to the gender and vibe of the voice. A well-crafted prompt can be the difference between a generic voice and one that truly fits your vision. In general, more descriptive and granular prompts tend to yield more accurate and nuanced results. The more detail you provide — including age, gender, tone, accent, pacing, emotion, style, and more - the better the model can interpret and deliver a voice that feels intentional and tailored.

However, sometimes short and simple prompts can also work, especially when you're aiming for a more neutral or broadly usable voice. For example, “A calm male narrator” might give you exactly what you need without going into detail — particularly if you're not trying to create a very specific character or style. The right level of detail depends on your use case. Are you building a fantasy character? A virtual assistant? A tired New Yorker in her 60s with a dry sense of humor? The more clearly you define it in your prompt, the closer the output will be to what you're imagining.

### Audio Quality

Audio quality refers to the clarity, cleanliness, and overall fidelity of the generated voice. By default, ElevenLabs aims to produce clean and natural-sounding audio — but if your project requires a specific level of quality, it's best to explicitly include it in your prompt.

For high-quality results, you can help the model by adding a phrase such as “**perfect audio quality**” or “**studio-quality recording**” to your voice description. This helps ensure the voice is rendered with maximum clarity, minimal distortion, and a polished finish.

<Warning>
  Including these types of phrases can sometimes reduce the accuracy of the prompt in general if the
  voice is very specific or niche.
</Warning>

There may also be creative cases where lower audio quality is intentional, such as when simulating a phone call, old radio broadcast, or found footage. In those situations, either leave out quality descriptors entirely or explicitly include phrases like:

* “Low-fidelity audio”
* “Poor audio quality”
* “Sounds like a voicemail”
* “Muffled and distant, like on an old tape recorder”

The placement of this phrase in your prompt is flexible — it can appear at the beginning or end, though we’ve found it works well at either.

### Age, Tone/Timbre and Gender

These three characteristics are the foundation of voice design, shaping the overall identity and emotional resonance of the voice. The more detail you provide, the easier it is for the AI to produce a voice that fits your creative vision — whether you're building a believable character, crafting a compelling narrator, or designing a virtual assistant.

#### Age

Describing the perceived age of the voice helps define its maturity, vocal texture, and energy. Use specific terms to guide the AI toward the right vocal quality.

**Useful descriptors:**

* “Adolscent male” / “adolescent female”
* “Young adult” / “in their 20s” / “early 30s”
* “Middle-aged man” / “woman in her 40s”
* “Elderly man” / “older woman” / “man in his 80s”

#### Tone/Timbre

Refers to the physical quality of the voice, shaped by pitch, resonance, and vocal texture. It’s distinct from emotional delivery or attitude.

**Common tone/timbre descriptors:**

* “Deep” / “low-pitched”
* “Smooth” / “rich”
* “Gravelly” / “raspy”
* “Nasally” / “shrill”
* “Airy” / “breathy”
* “Booming” / “resonant”
* “Light” / “thin”
* “Warm” / “mellow”
* “Tinny” / “metallic”

#### Gender

Gender often typically influences pitch, vocal weight, and tonal presence — but you can push beyond simple categories by describing the sound instead of the identity.

**Examples:**

* “A lower-pitched, husky female voice”
* “A masculine male voice, deep and resonant”
* “A neutral gender — soft and mid-pitched”

#### Accent

Accent plays a critical role in defining a voice’s regional, cultural, and emotional identity. If your project depends on an authentic sound — whether it's grounded in realism or stylized for character — being clear and deliberate about the desired accent is essential.

Phrase choice matters - certain terms tend to produce more consistent results. For example, “thick” often yields better results than “strong” when describing how prominent an accent should be. There is lots of trial and error to be had, and we encourage you to experiment with the wording and to be as creative and descriptive as possible.

* **Examples of clear accent prompts:**
  * “A middle-aged man with a thick French accent”
  * “A young woman with a slight Southern drawl”
  * “An old man with a heavy Eastern European accent”
  * “A cheerful woman speaking with a crisp British accent”
  * “A younger male with a soft Irish lilt”
  * “An authoritative voice with a neutral American accent”
  * “A man with a regional Australian accent, laid-back and nasal”

Avoid overly vague descriptors like “foreign” or “exotic” — they’re imprecise and can produce inconsistent results.

Combine accent with other traits like tone, age, or pacing for better control. E.g., “A sarcastic old woman with a thick New York accent, speaking slowly.”

For fantasy or fictional voices, you can suggest real-world accents as inspiration:

* “An elf with a proper thick British accent. He is regal and lyrical.”
* “A goblin with a raspy Eastern European accent.”

### Pacing

Pacing refers to the speed and rhythm at which a voice speaks. It's a key component in shaping the personality, emotional tone, and clarity of the voice. Being explicit about pacing is essential, especially when designing voices for specific use cases like storytelling, advertising, character dialogue, or instructional content.

Use clear language to describe how fast or slow the voice should speak. You can also describe how the pacing feels — whether it's steady, erratic, deliberate, or breezy. If the pacing shifts, be sure to indicate where and why.

**Examples of pacing descriptors:**

* “Speaking quickly” / “at a fast pace”
* “At a normal pace” / “speaking normally”
* “Speaking slowly” / “with a slow rhythm”
* “Deliberate and measured pacing”
* “Drawn out, as if savoring each word”
* “With a hurried cadence, like they’re in a rush”
* “Relaxed and conversational pacing”
* “Rhythmic and musical in pace”
* “Erratic pacing, with abrupt pauses and bursts”
* “Even pacing, with consistent timing between words”
* “Staccato delivery”

### Text to preview

Once you've written a strong voice prompt, the text you use to preview that voice plays a crucial role in shaping how it actually sounds. The preview text acts like a performance script — it sets the tone, pacing, and emotional delivery that the voice will attempt to match.

To get the best results, your preview text should complement the voice description, not contradict it. For example, if your prompt describes a “calm and reflective younger female voice with a slight Japanese accent,” using a sentence like “Hey! I can't stand what you’ve done with the darn place!!!” will clash with that intent. The model will try to reconcile that mismatch, often leading to unnatural or inconsistent results.

Instead, use sample text that reflects the voice’s intended personality and emotional tone. For the example above, something like “It’s been quiet lately... I’ve had time to think, and maybe that’s what I needed most.” supports the prompt and helps generate a more natural, coherent voice.

Additionally, we’ve found that longer preview texts tend to produce more stable and expressive results. Short phrases can sometimes sound abrupt or inconsistent, especially when testing subtle qualities like tone or pacing. Giving the model more context — a full sentence or even a short paragraph — allows it to deliver a smoother and more accurate representation of the voice.

### Parameters

#### Loudness

Controls the volume of the Text to Preview generation, and ultimately the voice once saved.

#### Guidance Scale

Dictates how closely the Prompt is adhered to. Higher values will stick to the prompt more strictly, but could result in poorer audio quality if the prompt is very niche, while lower values will allow the model to be more creative at the cost of prompt accuracy. Use a lower value if the performance and audio quality is generally more important than perfectly nailing the prompt. High values are recommended when accent or tone accuracy is of paramount importance.

### Attributes and Examples

<Note>
  Experiment with the way in which these descriptors are written. For example, “Perfect audio
  quality” can also be written as “the audio quality is perfect”. These can sometimes produce
  different results!
</Note>

| Attribute              | Examples                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Age                    | Young, younger, adult, old, elderly, in his/her 40s                                              |
| Accent                 | "thick" Scottish accent, "slight" Asian-American accent, Southern American accent                |
| Gender                 | Male, female, gender-neutral, ambiguous gender                                                   |
| Tone/Timbre/pitch      | Deep, warm, gravelly, smooth, shrill, buttery, raspy, nasally, throaty, harsh, robotic, ethereal |
| Pacing                 | Normal cadence, fast-paced, quickly, slowly, drawn out, calm pace, natural/conversational pace   |
| Audio Quality          | Perfect audio quality, audio quality is 'ok', poor audio quality                                 |
| Character / Profession | Pirate, businessman, farmer, politician, therapist, ogre, godlike being, TV announcer            |
| Emotion                | Energetic, excited, sad, emotional, sarcastic, dry                                               |
| Pitch                  | Low-pitched, high-pitched, normal pitch                                                          |

### Example Prompts and Text Previews

| Voice Type                     | Prompt/Description                                                                                                                                                                                                                                                                                     | Text Preview                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Guidance Scale |
| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
| Female Sports Commentator      | A high-energy female sports commentator with a thick British accent, passionately delivering play-by-play coverage of a football match in a very quick pace. Her voice is lively, enthusiastic, and fully immersed in the action.                                                                      | OH MY WORD — WHAT A GOAL! She picks it up just past midfield, dances through TWO defenders like they're not even THERE, and absolutely SMASHES it into the top corner! The goalkeeper had NO CHANCE! That is WORLD-CLASS from the young forward, and the crowd is on their FEET! This match has come ALIVE, and you can FEEL the momentum SHIFTING!                                                                                                                                                                                                      | 25%            |
| Drill Sergeant                 | An army drill sergeant shouting at his team of soldiers. He sounds angry and is speaking at a fast pace.                                                                                                                                                                                               | LISTEN UP, you sorry lot! I didn't come here to babysit — I came to BUILD SOLDIERS! You move when I say move, and you breathe when I say breathe! You've got ten seconds to fall in line or you'll regret it!!                                                                                                                                                                                                                                                                                                                                           | 25%            |
| Evil Ogre                      | A massive evil ogre speaking at a quick pace. He has a silly and resonant tone.                                                                                                                                                                                                                        | "Your weapons are but toothpicks to me. \[laughs] Surrender now and I may grant you a swift end. I've toppled kingdoms and devoured armies. What hope do you have against me?"                                                                                                                                                                                                                                                                                                                                                                           | 30%            |
| Relatable British Entrepreneur | Excellent audio quality. A man in his 30s to early 40s with a thick British accent speaking at a natural pace like he's talking to a friend.                                                                                                                                                           | \[laughs] See, that's the thing. YOU see a company, while I see... \[lip smacks] I see a promise, ya know what I mean? \[exhales] We don't build just to profit, we build to, to UPLIFT! If our technology doesn't leave the world kinder, smarter, and more connected than we found it… \[sighs] then what are we even doing here?                                                                                                                                                                                                                      | 40%            |
| Southern Woman                 | An older woman with a thick Southern accent. She is sweet and sarcastic.                                                                                                                                                                                                                               | "Well sugar, if all we ever do is chase titles and trophies, we're gonna miss the whole darn point. \[light chuckle] I'd rather build somethin' that makes folks' lives easier—and if I can do it in heels with a smile and a touch of sass, even better."                                                                                                                                                                                                                                                                                               | 35%            |
| Movie Trailer Voice            | Dramatic voice, used to build anticipation in movie trailers, typically associated with action or thrillers                                                                                                                                                                                            | "In a world on the brink of chaos, one hero will rise. Prepare yourself for a story of epic proportions, coming soon to the big screen."                                                                                                                                                                                                                                                                                                                                                                                                                 | 20%            |
| Squeaky Mouse                  | A cute little squeaky mouse                                                                                                                                                                                                                                                                            | "I may be small, but my attitude is anything but! \[giggles] Watch it, big feet, or I'll give your toes a nibble you won't forget!"                                                                                                                                                                                                                                                                                                                                                                                                                      | 20%            |
| Angry Pirate                   | An angry old pirate, loud and boisterous                                                                                                                                                                                                                                                               | "I've faced storms that would turn your hair white and sea monsters that would make your knees quake. You think you can cross Captain Blackheart and live to tell the tale?"                                                                                                                                                                                                                                                                                                                                                                             | 30%            |
| New Yorker                     | Deep, gravelly thick New York accent, tough and world-weary, often cynical                                                                                                                                                                                                                             | "I've been walking these streets longer than you can imagine, kid. There's nothing you can say or do that'll surprise me anymore."                                                                                                                                                                                                                                                                                                                                                                                                                       | 40%            |
| Mad Scientist                  | A voice of an eccentric scientific genius with rapid, erratic speech patterns that accelerate with excitement. His German-tinged accent becomes more pronounced when agitated. The pitch varies widely from contemplative murmurs to manic exclamations, with frequent eruptions of maniacal laughter. | "I am doctor Heinrich, revolutionary genius rejected by the narrow-minded scientific establishment! Bah! They called my theories impossible, my methods unethical—but who is laughing now? (maniacal laughter) For twenty years I have perfected my creation in this mountain laboratory, harnessing energies beyond mortal comprehension! The fools at the academy will regret their mockery when my quantum destabilizer reveals the multiverse. Or perhaps new life forms... the experiment has certain unpredictable variables... FASCINATING ones!" | 38%            |


# Payouts

> Earn rewards by sharing your voice in the Voice Library.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2827fdd8be3ad39ff50a5fe9b0a5d4d7a2dcf4aa7f1fc6a8406d451c1dd3d30d/assets/images/product-guides/voices/payouts-product-feature.png" alt="Payouts" />

## Overview

The [Payouts](https://elevenlabs.io/payouts) system allows you to earn rewards for sharing voices in the [Voice library](/docs/creative-platform/voices/voice-library). ElevenLabs uses <a href="https://stripe.com/connect">Stripe Connect</a> to process reward payouts.

## Account setup

To set up your Payouts account:

* Click on your profile icon in the top right corner and select ["Payouts"](https://elevenlabs.io/app/payouts).

<Frame background="subtle">
  ![Payouts overview](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a8a2f7f41a9d548644fbd90d54d416e1d1811c358c8a46f8b64f78b818af63d9/assets/images/product-guides/voices/payouts-overview.png)
</Frame>

* Follow the prompts from Stripe Connect to complete the account setup.

## Tracking usage and earnings

* You can track the usage of your voices by going to ["My Voices"](https://elevenlabs.io/app/voice-lab), clicking "View" to open the detailed view for your voice, then clicking the sharing icon at the bottom. Once you have the Sharing Options open, click "View Metrics".
* The rewards you earn are based on the options you selected when [sharing your voice in the Voice Library](/docs/creative-platform/voices/voice-library#sharing-a-professional-voice-clone).
* You can also see your all-time earnings and past payouts by going back to your Payouts page.

## Reader app rewards

* If your voice is marked as **[High-Quality](/docs/creative-platform/voices/voice-library#quality-1)** and you have activated the "Available in ElevenReader" toggle, your voice will made be available in the [ElevenReader app](https://elevenlabs.io/text-reader). Rewards for ElevenReader are reported separately – to view your Reader App rewards, check the "ElevenReader" box on your "View Metrics" screen.

## Things to know

* Rewards accumulate frequently throughout the day, but payouts typically happen once a week as long as you have an active paid subscription and your accrued payouts exceed the minimum threshold. In most cases this is \$10, but some countries may have a higher threshold.

* You can see your past payouts by going to your [Payouts](https://elevenlabs.io/app/payouts) page in the sidebar.

## Supported countries

* Currently, Stripe Connect is not supported in all countries. We are constantly working to expand our reach for Payouts and plan to add availability in more countries when possible.

<Accordion title="Supported countries">
  - Argentina
  - Australia
  - Austria
  - Belgium
  - Bulgaria
  - Canada
  - Chile
  - Colombia
  - Croatia
  - Cyprus
  - Czech Republic
  - Denmark
  - Estonia
  - Finland
  - France
  - Germany
  - Greece
  - Hong Kong SAR
  - China
  - Hungary
  - Iceland
  - India
  - Indonesia
  - Ireland
  - Israel
  - Italy
  - Japan
  - Latvia
  - Liechtenstein
  - Lithuania
  - Luxembourg
  - Malaysia
  - Malta
  - Mexico
  - Monaco
  - Netherlands
  - New Zealand
  - Nigeria
  - Norway
  - Peru
  - Philippines
  - Poland
  - Portugal
  - Qatar
  - Romania
  - Saudi Arabia
  - Singapore
  - Slovakia
  - Slovenia
  - South Africa
  - South Korea
  - Spain
  - Sweden
  - Switzerland
  - Thailand
  - Taiwan
  - Turkey
  - United Arab Emirates
  - United Kingdom
  - United States
  - Uruguay
  - Vietnam
</Accordion>


# Audio Native

> Easily embed ElevenLabs on any web page.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/46d22deceeb0c48519f5c98400269b282f6919dc7d8e97baec7e2ca4a215dc8c/assets/images/product-guides/audio-native/audio-native-product-feature.png" alt="Audio Native" />

## Overview

Audio Native is an embedded audio player that automatically voices content of a web page using ElevenLab’s [Text to Speech](/docs/creative-platform/playground/text-to-speech) service. It can also be used to embed pre-generated content from a project into a web page. All it takes to embed on your site is a small HTML snippet. In addition, Audio Native provides built-in metrics allowing you to precisely track audience engagement via a listener dashboard.

The end result will be a Audio Native player that can narrate the content of a page, or, like in the case below, embed pre-generated content from a project:

<iframe width="100%" height="90" seamless src="https://elevenlabs.io/player/index.html?publicUserId=4d7f6f3d38ae27705f5b516ffd3e413a09baa48667073d385e5be1be773eaf69&projectId=gLj1spzTwuTgKuOtyfnX&small=true&textColor=rgba(0,%200,%200,%201)&backgroundColor=rgba(255,%20255,%20255,%201)" />

## Guide

<Steps>
  <Step title="Navigate to Audio Native">
    In the ElevenLabs dashboard, under "Audio Tools" navigate to ["Audio Native"](/app/audio-native).
  </Step>

  <Step title="Configure player appearance">
    Customize the player appearance by selecting background and text colors.
  </Step>

  <Step title="Configure allowed sites">
    The URL allowlist is the list of web pages that will be permitted to play your content.

    You can choose to add a specific web page (e.g. `https://elevenlabs.io/blog`) or add a whole domain to the allowlist (e.g. `http://elevenlabs.io`). If a player is embedded on a page that is not in the allowlist, it will not work as intended.
  </Step>

  <Step title="Get embed code">
    Once you've finished configuring the player and allowlist, copy the embed code and paste it into your website's source code.
  </Step>
</Steps>

## Technology-specific guides

To integrate Audio Native into your web techology of choice, see the following guides:

<CardGroup cols={4}>
  <Card title="React" icon="brands react" href="/docs/creative-platform/audio-tools/audio-native/react" />

  <Card title="Ghost" icon="duotone ghost" href="/docs/creative-platform/audio-tools/audio-native/ghost" />

  <Card title="Squarespace" icon="brands squarespace" href="/docs/creative-platform/audio-tools/audio-native/squarespace" />

  <Card title="Framer" icon="duotone browser" href="/docs/creative-platform/audio-tools/audio-native/framer" />

  <Card title="Webflow" icon="brands webflow" href="/docs/creative-platform/audio-tools/audio-native/webflow" />

  <Card title="Wordpress" icon="brands wordpress" href="/docs/creative-platform/audio-tools/audio-native/word-press" />

  <Card title="Wix" icon="brands wix" href="/docs/creative-platform/audio-tools/audio-native/wix" />
</CardGroup>

## Using the API

You can use the [Audio Native API](/docs/api-reference/audio-native/create) to programmatically create an Audio Native player for your existing content.

<CodeBlocks>
  ```python title="Python"
  from elevenlabs import ElevenLabs

  elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
  )
  response = elevenlabs.audio_native.create(
  name="name",
  )

  # Use the snippet in response.html_snippet to embed the player on your website

  ```

  ```javascript title="JavaScript"
  import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

  const elevenlabs = new ElevenLabsClient({ apiKey: "YOUR_API_KEY" });
  const { html_snippet } = await elevenlabs.audioNative.create({
      name: "my-audio-native-player"
  });

  // Use the HTML code in html_snippet to embed the player on your website
  ```
</CodeBlocks>

## Settings

<AccordionGroup>
  <Accordion title="Voice and model">
    ### Voices

    To configure the voice and model that will be used to read the content of the page, navigate to the "Settings" tab and select the voice and model you want to use.
  </Accordion>

  <Accordion title="Pronunciation dictionaries">
    ### Pronunciation dictionaries

    Sometimes you may want to specify the pronunciation of certain words, such as character or brand names, or specify how acronyms should be read. Pronunciation dictionaries allow this functionality by enabling you to upload a lexicon or dictionary file that includes rules about how specified words should be pronounced, either using a phonetic alphabet (phoneme tags) or word substitutions (alias tags).

    Whenever one of these words is encountered in a project, the AI will pronounce the word using the specified replacement. When checking for a replacement word in a pronunciation dictionary, the dictionary is checked from start to end and only the first replacement is used.
  </Accordion>
</AccordionGroup>


# Audio Native with React

> Integrate Audio Native into your React apps.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

This guide will show how to integrate Audio Native into React apps. The focus will be on a Next.js project, but the underlying concepts will work for any React based application.

<Steps>
  <Step title="Create an Audio Native React component">
    After completing the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native), you'll have an embed code snippet. Here's an example snippet:

    ```html title="Embed code snippet"
      <div
        id="elevenlabs-audionative-widget"
        data-height="90"
        data-width="100%"
        data-frameborder="no"
        data-scrolling="no"
        data-publicuserid="public-user-id"
        data-playerurl="https://elevenlabs.io/player/index.html"
        data-projectid="project-id"
      >
        Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
      </div>
      <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    We can extract the data from the snippet to create a customizable React component.

    ```tsx title="ElevenLabsAudioNative.tsx" maxLines=0
    // ElevenLabsAudioNative.tsx

    'use client';

    import { useEffect } from 'react';

    export type ElevenLabsProps = {
      publicUserId: string;
      textColorRgba?: string;
      backgroundColorRgba?: string;
      size?: 'small' | 'large';
      children?: React.ReactNode;
    };

    export const ElevenLabsAudioNative = ({
      publicUserId,
      size,
      textColorRgba,
      backgroundColorRgba,
      children,
    }: ElevenLabsProps) => {
      useEffect(() => {
        const script = document.createElement('script');

        script.src = 'https://elevenlabs.io/player/audioNativeHelper.js';
        script.async = true;
        document.body.appendChild(script);

        return () => {
          document.body.removeChild(script);
        };
      }, []);

      return (
        <div
          id="elevenlabs-audionative-widget"
          data-height={size === 'small' ? '90' : '120'}
          data-width="100%"
          data-frameborder="no"
          data-scrolling="no"
          data-publicuserid={publicUserId}
          data-playerurl="https://elevenlabs.io/player/index.html"
          data-small={size === 'small' ? 'True' : 'False'}
          data-textcolor={textColorRgba ?? 'rgba(0, 0, 0, 1.0)'}
          data-backgroundcolor={backgroundColorRgba ?? 'rgba(255, 255, 255, 1.0)'}
        >
          {children ? children : 'Elevenlabs AudioNative Player'}
        </div>
      );
    };

    export default ElevenLabsAudioNative;
    ```

    The above component can be found on [GitHub](https://github.com/elevenlabs/elevenlabs-examples/blob/main/examples/audio-native/react/ElevenLabsAudioNative.tsx).
  </Step>

  <Step title="Use the Audio Native component">
    Before using the component on your page, you need to retrieve your public user ID from the original code snippet. Copy the contents of `data-publicuserid` from the embed code snippet and insert it into the `publicUserId` prop of the component.

    ```tsx title="page.tsx" maxLines=0
    import { ElevenLabsAudioNative } from './path/to/ElevenLabsAudioNative';

    export default function Page() {
      return (
        <div>
          <h1>Your Page Title</h1>

          // Insert the public user ID from the embed code snippet
          <ElevenLabsAudioNative publicUserId="<your-public-user-id>" />

          <p>Your page content...</p>
        </div>
      );
    }
    ```
  </Step>

  <Step title="Customize the player with component props">
    The component props can be used to customize the player. For example, you can change the size, text color, and background color.

    ```tsx title="page.tsx" maxLines=0
    import { ElevenLabsAudioNative } from './path/to/ElevenLabsAudioNative';

    export default function Page() {
      return (
        <div>
          <h1>Your Page Title</h1>

          <ElevenLabsAudioNative
            publicUserId="<your-public-user-id>"
            size="small"
            textColorRgba="rgba(255, 255, 255, 1.0)"
            backgroundColorRgba="rgba(0, 0, 0, 1.0)"
          />

          <p>Your page content...</p>
        </div>
      );
    }
    ```
  </Step>
</Steps>


# Audio Native with Ghost

> Integrate Audio Native into your Ghost blog.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Add HTML to your blog post">
    Navigate to your Ghost blog, sign in and open the settings page for the blog post you wish to narrate.
  </Step>

  <Step title="Add the embed code to your blog post">
    Click the "+" symbol on the left and select "HTML" from the menu.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5a2bae6de46f35e49eeaef8ad92323d9717e5af5b00ad05a7670a30ec8f4696c/assets/images/product-guides/audio-native/audio-native-ghost-1.webp" alt="Audio Native" />

    Paste the Audio Native embed code into the HTML box and press enter.

    ```html title="Embed code snippet"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2783aa5f50f84ce712957ccb1504381e4248b49b5ca408173c583a40bd38d58e/assets/images/product-guides/audio-native/audio-native-ghost-2.webp" alt="Audio Native" />
  </Step>

  <Step title="Update the blog post">
    Click the "Update" button in the top right corner of the editor, which should now be highlighted in green text.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1625ff60cbf3c92760d918a298ed65fe6f0911c345efbf9999185cf4fab95014/assets/images/product-guides/audio-native/audio-native-ghost-3.webp" alt="Audio Native" />
  </Step>

  <Step title="Navigate to the live version of the blog post">
    Finally, navigate to the live version of the blog post. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/20730d8df4528041314d44667d0f9418af10636144af722c1cfa2e7fe48b6107/assets/images/product-guides/audio-native/audio-native-ghost-4.webp" alt="Audio Native" />
  </Step>
</Steps>


# Audio Native with Squarespace

> Integrate Audio Native into your Squarespace sites.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Add HTML to your blog post">
    Navigate to your Squarespace site, sign in and open the page you wish to add narration to.
  </Step>

  <Step title="Add the embed code to your blog post">
    Click the "+" symbol on the spot you want to place the Audio Native player and select "Code" from the menu.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/aedf2e008d7a58a1c502b0b71fc674397928102ce07202a31eec415360d98490/assets/images/product-guides/audio-native/audio-native-squarespace-1.png" alt="Audio Native" />

    Paste the Audio Native embed code into the HTML box and press enter.

    ```html title="Embed code snippet"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c9bc7a9212ad6934ebd100aab3fc6d35436e01058d1ce41cf6ac9994a1aba91c/assets/images/product-guides/audio-native/audio-native-squarespace-2.png" alt="Audio Native" />
  </Step>

  <Step title="Update the blog post">
    Click the "Save" button in the top right corner of the editor, which should now be highlighted.
  </Step>

  <Step title="Navigate to the live version of the blog post">
    Finally, navigate to the live version of the blog post. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e5dd2d8d5c0a5827527911cfab8bb32c5c1af58947a0eeb5e6e6e2df8687de44/assets/images/product-guides/audio-native/audio-native-squarespace-3.png" alt="Audio Native" />
  </Step>
</Steps>


# Audio Native with Framer

> Integrate Audio Native into your Framer websites.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Add Audio Native script to your page">
    Navigate to your Framer page, sign in and go to your site settings. From the Audio Native embed code, extract the `<script>` tag and paste it in the "End of `<body>` tag" field.

    ```html title="Embed script "
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/00efa5ae0c085f442c015ebcf69066cc42c8e20d1c24c907444dd750e159dd4a/assets/images/product-guides/audio-native/audio-native-framer-1.webp" alt="Audio Native" />
  </Step>

  <Step title="Add an Embed Element">
    On your Framer blog page, add an Embed Element from Utilities.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/601d4256f5826613e90b5ad75bd92abc7b218944f31cea0a14cfad0677f080ee/assets/images/product-guides/audio-native/audio-native-framer-2.webp" alt="Audio Native" />

    In the config for the Embed Element, switch the type to HTML and paste the `<div>` snippet from the Audio Native embed code into the HTML box.

    ```html title="Embed div"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/42ba6037aedc4982495e8ea0ba8f6a23601d1309a6c67f310c8ed326382022b9/assets/images/product-guides/audio-native/audio-native-framer-3.webp" alt="Audio Native" />
  </Step>

  <Step title="Publish your changes">
    Finally, publish your changes and navigate to the live version of your page. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/86a311d5bdca2b406a9ee85d7f18a357f7e41dd31545b4b90a92ce04880b1e80/assets/images/product-guides/audio-native/audio-native-framer-4.webp" alt="Audio Native" />
  </Step>
</Steps>


# Audio Native with Webflow

> Integrate Audio Native into your Webflow sites.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Add HTML to your blog post">
    Navigate to your Webflow blog, sign in and open the editor for the blog post you wish to narrate.
  </Step>

  <Step title="Add the embed code to your blog post">
    Click the "+" symbol in the top left and select "Code Embed" from the Elements menu.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/463029e96318cf16fa0b207019206a4e8e7b1bf44ab4203ca9811037bc2c22a4/assets/images/product-guides/audio-native/audio-native-webflow-1.webp" alt="Audio Native" />

    Paste the Audio Native embed code into the HTML box and click "Save & Close".

    ```html title="Embed code snippet"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cdfc41cfbb4ba58fecc2173ab4b247037c34a7e0beb35cfd55a492a8ca2b74bf/assets/images/product-guides/audio-native/audio-native-webflow-2.webp" alt="Audio Native" />
  </Step>

  <Step title="Re-position the code embed">
    In the Navigator, place the code embed where you want it to appear on the page.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/43b6853dad99b80ed8c88d1f7a5400c96bad1cf7455213e6bc6c025031685c44/assets/images/product-guides/audio-native/audio-native-webflow-3.webp" alt="Audio Native" />
  </Step>

  <Step title="Publish your changes">
    Finally, publish your changes and navigate to the live version of the blog post. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4ec1a4eac0888c6b7f5df5e5669581b5b2a38967295eb2a5bc8fc7acc409b840/assets/images/product-guides/audio-native/audio-native-webflow-4.webp" alt="Audio Native" />
  </Step>
</Steps>


# Audio Native with WordPress

> Integrate Audio Native into your WordPress sites.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Install the WPCode plugin">
    Install the [WPCode plugin](https://wpcode.com/) into your WordPress website to embed HTML code.
  </Step>

  <Step title="Create a new code snippet">
    In the WordPress admin console, click on "Code Snippets". Add the Audio Native embed code to the new code snippet.

    ```html title="Embed code snippet"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ce6368db32162ddccd68639525a54eeb477eacf3ecd64f9fac559f7a4bac1e01/assets/images/product-guides/audio-native/audio-native-wordpress-1.webp" alt="Audio Native" />

    Pick "Auto Insert" for the insert method and set the location to be "Insert Before Content".

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/301598cd60b04b9df9465b057eeb955518b94dfbf676c9cbfee194fe6653fa90/assets/images/product-guides/audio-native/audio-native-wordpress-2.webp" alt="Audio Native" />
  </Step>

  <Step title="Publish your changes">
    Finally, publish your changes and navigate to the live version of the blog post. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d28e7eb952db6f03f5c1007f43eea0dcda3dc5413d98ab2a3aa5610d242ed8b8/assets/images/product-guides/audio-native/audio-native-wordpress-3.webp" alt="Audio Native" />
  </Step>
</Steps>


# Audio Native with Wix

> Integrate Audio Native into your Wix sites.

<Info>
  Follow the steps in the [Audio Native overview](/docs/creative-platform/audio-tools/audio-native)
  to get started with Audio Native before continuing with this guide.
</Info>

<Steps>
  <Step title="Add HTML to your blog post">
    Navigate to your Wix site, sign in and open the settings page for the page you wish to narrate.
  </Step>

  <Step title="Add the embed code to your blog post">
    Click the "+" symbol at the top of your content and select "HTML Code" from the menu.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5f9626bac119a2647568eac68a7f47877c5590a0f9d40bb77d7d34288d82852c/assets/images/product-guides/audio-native/audio-native-wix-1.webp" alt="Audio Native" />

    Paste the Audio Native embed code into the HTML box and click "Save".

    ```html title="Embed code snippet"
        <div
            id="elevenlabs-audionative-widget"
            data-height="90"
            data-width="100%"
            data-frameborder="no"
            data-scrolling="no"
            data-publicuserid="public-user-id"
            data-playerurl="https://elevenlabs.io/player/index.html"
            data-projectid="project-id"
        >
            Loading the <a href="https://elevenlabs.io/text-to-speech" target="_blank" rel="noopener">Elevenlabs Text to Speech</a> AudioNative Player...
        </div>
        <script src="https://elevenlabs.io/player/audioNativeHelper.js" type="text/javascript"></script>
    ```

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/719f1f2d8f01aa94ea6550fc62666ec4c4dac024e3f26a8eed925de0f8c54e3d/assets/images/product-guides/audio-native/audio-native-wix-2.webp" alt="Audio Native" />
  </Step>

  <Step title="Publish the page">
    Click the "Publish" button in the top right corner of the editor.
  </Step>

  <Step title="Navigate to the live version of the blog post">
    Finally, navigate to the live version of the blog post. You should see a message to let you know that the Audio Native project is being created. After a few minutes the text in your blog will be converted to an audio article and the embedded audio player will appear.

    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4bf9e321cac2007f1cf570410dc2e6a610fe209acad0c0caca4a049484e7ff22/assets/images/product-guides/audio-native/audio-native-wix-3.webp" alt="Audio Native" />
  </Step>
</Steps>


# Voiceover studio

> A guide on how to create long-form content with ElevenLabs Voiceover Studio

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/051b3139b84d462fcaa5bcf11d7ca2e7be093fa226ac08e7d827c447ee97ae4a/assets/images/product-guides/voiceover-studio/voiceover-studio.png" alt="Voiceover studio" />

## Overview

Voiceover Studio combines the audio timeline with our Sound Effects feature, giving you the ability to write a dialogue between any number of speakers, choose those speakers, and intertwine your own creative sound effects anywhere you like.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/GBdOQClluIA?autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Guide

<Steps>
  <Step title="Navigate to the Voiceover studio">
    In the ElevenLabs dashboard, click on the "Voiceover Studio" option in the sidebar under "Audio
    Tools".
  </Step>

  <Step title="Create a new voiceover">
    Click the "Create a new voiceover" button to begin. You can optionally upload video or audio to
    create a voiceover from.
  </Step>

  <Step title="Modify the voiceover with the timeline">
    On the bottom half of your screen, use the timeline to add and edit voiceover clips plus add
    sound effects.
  </Step>

  <Step title="Export your voiceover">
    Once you're happy with your voiceover, click the "Export" button in the bottom right, choose the
    format you want and either view or download your voiceover.
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="How does the timeline work?">
    ### Timeline

    The timeline is a linear representation of your Voiceover project. Each row represents a track, and on the far left section you have the track information for voiceover or SFX tracks. In the middle, you can create the clips that represent when a voice is speaking or a SFX is playing. On the right-hand side, you have the settings for the currently selected clip.
  </Accordion>

  <Accordion title="How do I add tracks?">
    ### Adding Tracks

    To add a track, click the "Add Track" button in the bottom left of the timeline. You can choose to add a voiceover track or an SFX track.

    There are three types of tracks you can add in the studio: Voiceover tracks, SFX tracks and uploaded audio.

    * **Voiceover Tracks:** Voiceover tracks create new Speakers. You can click and add clips on the timeline wherever you like. After creating a clip, start writing your desired text on the speaker cards above and click "Generate". Similar to Dubbing Studio, you will also see a little cogwheel on each Speaker track - simply click on it to adjust the voice settings or replace any speaker with a voice directly from your Voices - including your own Professional Voice Clone if you have created one.

    * **SFX Tracks:** Add a SFX track, then click anywhere on that track to create a SFX clip. Similar to our independent SFX feature, simply start writing your prompt in the Speaker card above and click "Generate" to create your new SFX audio. You can lengthen or shorten SFX clips and move them freely around your timeline to fit your project - make sure to press the "stale" button if you do so.

    * **Uploaded Audio:** Add an audio track including background music or sound effects. It's best to avoid uploading audio with speakers, as any speakers in this track will not be detected, so you won't be able to translate or correct them.
  </Accordion>

  <Accordion title="How does this differ from Dubbing Studio?">
    ### Key Differences from Dubbing Studio

    If you chose not to upload a video when you created your Voiceover project, then the entire timeline is yours to work with and there are no time constraints. This differs from Dubbing Studio as it gives you a lot more freedom to create what you want and adjust the timing more easily.

    When you Add a Voiceover Track, you will instantly be able to create clips on your timeline. Once you create a Voiceover clip, begin by writing in the Speaker Card above. After generating that audio, you will notice your clip on the timeline will automatically adjust its length based on the text prompt - this is called "Dynamic Generation". This option is also available in Dubbing Studio by right-clicking specific clips, but because syncing is more important with dubbed videos, the default generation type there is "Fixed Generation," meaning the clips' lengths are not affected.
  </Accordion>

  <Accordion title="How are credits deducted with Voiceover Studio?">
    ### Credit Costs

    Voiceover Studio does not deduct credits to create your initial project. Credits are deducted every time material is generated. Similar to Speech-Synthesis, credit costs for Voiceover Clips are based on the length of the text prompt. SFX clips will deduct 80 credits per generation.

    If you choose to Dub (translate) your Voiceover Project into different languages, this will also cost additional credits depending on how much material needs to be generated. The cost is 1 credit per character for the translation, plus the cost of generating the new audio for the additional languages.
  </Accordion>

  <Accordion title="How do I upload a script?">
    ### Uploading Scripts

    With Voiceover Studio, you have the option to upload a script for your project as a CSV file. You can either include speaker name and line, or speaker name, line, start time and end time. To upload a script, click on the cog icon in the top right hand corner of the page and select "Import Script".

    Scripts should be provided in the following format:

    ```
    speaker,line
    ```

    Example input:

    ```
    speaker,line
    Joe,"Hey!"
    Maria,"Oh, hi Joe! It's been a while."
    ```

    You can also provide start and end times for each line in the following format:

    ```
    speaker,line,start_time,end_time
    ```

    Example input:

    ```
    speaker,line,start_time,end_time
    Joe,"Hey!",0.1,1.5
    Maria,"Oh, hi Joe! It's been a while.",1.6,2.0
    ```

    Once your script has imported, make sure to assign voices to each speaker before you generate the audio. To do this, click the cog icon in the information for each track, on the left.

    If you don't specify start and end times for your clips, Voiceover Studio will estimate how long each clip will be, and distribute them along your timeline.
  </Accordion>

  <Accordion title="What's the difference between Dynamic Duration and Fixed Duration?">
    ### Dynamic Duration

    By default, Voiceover Studio uses Dynamic Duration, which means that the length of the clip will vary depending on the text input and the voice used. This ensures that the audio sounds as natural as possible, but it means that the length of the clip might change after the audio has been generated. You can easily reposition your clips along the timeline once they have been generated to get a natural sounding flow. If you click "Generate Stale Audio", or use the generate button on the clip, the audio will be generated using Dynamic Duration.

    This also applies if you do specify the start and end time for your clips. The clips will generate based on the start time you specify, but if you use the default Dynamic Duration, the end time is likely to change once you generate the audio.

    ### Fixed Duration

    If you need the clip to remain the length specified, you can choose to generate with Fixed Duration instead. To do this, you need to right click on the clip and select "Generate Audio Fixed Duration". This will adjust the length of the generated audio to fit the specified length of the clip. This could lead to the audio sounding unnaturally quick or slow, depending on the length of your clip.

    If you want to generate multiple clips at once, you can use shift + click to select multiple clips for a speaker at once, then right click on one of them to select "Generate Audio Fixed Duration" for all selected clips.
  </Accordion>
</AccordionGroup>


# Voice isolator

> A guide on how to remove background noise from audio recordings.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/MeUaINLnww0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Voice isolator is a tool that allows you to remove background noise from audio recordings.

## Guide

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9a60aeca7a345ff15d3223b85a8fe2ce7798fb7815c8c013916cab745b45408c/assets/images/product-guides/voice-isolator/voice-isolator.png" alt="Voice isolator" />

To use the voice isolator app, navigate to [Voice Isolator](https://elevenlabs.io/app/voice-isolator) under the Audio Tools section. Here you can upload or drag and drop your audio file into the app, or record a new audio file with your device's microphone.

Click "Isolate voice" to start the process. The app will isolate the voice from the background noise and return a new audio file with the isolated voice. Once the process is complete, you can download the audio file or play it back in the app.

The voice isolator functionality is also available via the [API](/docs/api-reference/audio-isolation/convert) to easily integrate this functionality into your own applications.

<CardGroup>
  <Card title="Voice isolator app" href="https://elevenlabs.io/app/voice-isolator">
    Use the voice isolator app.
  </Card>

  <Card title="API reference" href="/docs/api-reference/audio-isolation/convert">
    Use the voice isolator API.
  </Card>
</CardGroup>


# AI speech classifier

> A guide on how to detect AI audio

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/73f6b500e4735d28f34c3fee8276a621cd05fb2bde9cca0e66e33d8f051cd4ac/assets/images/product-guides/ai-speech-classifier/ai-speech-classifier.png" alt="AI speech classifier" />

## Overview

The AI speech classifier is a tool that allows you to detect if an audio file was generated by ElevenLabs.

## Guide

<Steps>
  <Step title="Navigate to the AI speech classifier page">
    Select the "AI speech classifier" option from the sidebar under "Audio Tools" in the ElevenLabs
    dashboard.
  </Step>

  <Step title="Upload an audio file">
    Click the "Upload audio" button upload an audio file and begin scanning.
  </Step>

  <Step title="Analyze the audio file">
    The AI speech classifier will analyze the audio file and provide a result.
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="How accurate is the AI speech classifier?">
    Our classifier maintains high accuracy (99% precision, 80% recall) for audio files generated
    with ElevenLabs that have not been modified. We will continue to improve this tool, while
    exploring other detection tools that provide transparency about how content was created.
  </Accordion>

  <Accordion title="Does using the tool cost me anything?">
    No, the tool is free for all to use.
  </Accordion>

  <Accordion title="Do I have to be logged in to use the tool?">
    A [web version](https://elevenlabs.io/ai-speech-classifier) of the tool is available for you to
    use without having to log in.
  </Accordion>
</AccordionGroup>


# Productions

> Human-edited transcripts, subtitles, dubs and audiobooks at scale.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/mlbdLyGQgAg" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Productions is a service that lets you order human-edited transcripts, subtitles, dubs, and audiobooks directly on the ElevenLabs platform. A team of expert linguists and localization professionals vetted and trained by ElevenLabs works on your content and delivers you polished final assets.

<Frame>
  ![Productions Get Human Review Option](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cd072dfc01c9b277960c0583a3900ca963ee0ca766f204f5fac602117f5a8174/assets/images/productions/productions-home.png)
</Frame>

## Why use Productions?

* <b>Quality at scale</b>: Your audience cares – let native speakers ensure your multilingual
  content looks, sounds, and feels natural.
* <b>Speed and cost</b>: 5-10x cheaper than traditional LSP services and ready in days vs. weeks or
  months.
* <b>Ease of use</b>: No more email chains or procurement threads – get your content polished and
  ready for your audiences in just a few clicks.

## Services

Click the cards below to learn more about our different Productions services:

<CardGroup cols={2}>
  <Card title="Transcripts" icon="duotone pen-clip" href="/docs/creative-platform/services/productions/transcripts">
    Reviewed by native speakers for maximum accuracy
  </Card>

  <Card title="Subtitles" icon="duotone subtitles" href="/docs/creative-platform/services/productions/subtitles">
    Adapted to formatting and accessibility requirements
  </Card>

  <Card title="Dubbing" icon="duotone microphone" href="/docs/creative-platform/services/productions/dubbing">
    Script translation and audio generation by localization professionals
  </Card>

  <Card title="Audiobooks (coming soon)" icon="duotone book">
    Support for single and multi-speaker voice casting
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Upload new files or select existing files">
    **Ordering a new asset**: head to the [Productions](https://elevenlabs.io/app/productions) page of your ElevenLabs account and create a new order. You may also see a *Productions* option when using the order dialog for other products like [Speech to Text](https://elevenlabs.io/app/speech-to-text) or [Dubbing](https://elevenlabs.io/app/dubbing)

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1d18c451ce48b05fb9943a11707e86cd7a8c883b30e7557551f1bdccc05851a9/assets/images/productions/productions-stt-dialog.png" alt="Productions STT Dialog" />
    </Frame>

    **Starting from an existing asset**: you can also order human-edited versions of existing assets in your ElevenLabs account. Look for the 'Get human review' button in the top right of the editor view for this option.

    <Frame background="subtle">
      ![Productions Get Human Review Option](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b25a0e08ad610f29b352c4cf9a1ef8f29061487c61f51de7c5c0b2cfb0533863/assets/images/productions/productions-get-human-review.png)
    </Frame>
  </Step>

  <Step title="Review and confirm quote">
    Once you upload a file, select a language, and choose your style guide options, you'll see a quote with an **estimated** price for the settings you've chosen.

    When you click *Continue*, the file will be analyzed and the final price will be returned.

    <Frame background="subtle">
      ![Productions quote](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ae927b61d36a1b1bd5e2d01f8213acc89c5609a1823bef127a20a92510b9022f/assets/images/productions/productions-quote.png)
    </Frame>

    <Info>
      You may see an error message that there is no capacity available for the language you're interested in. If this happens, please check back later! Productions is a new service, and additional capacity will be added as it scales up.
    </Info>
  </Step>

  <Step title="Complete checkout">
    After reviewing the final quote, click *Checkout* and follow the dialog instructions to complete your payment.

    <Info>
      Enterprise orders are deducted from workspace credits instead of going through our payment processor. If you have any questions or run into access issues, please contact your workspace admin or reach out to us at 

      [productions@elevenlabs.io](mailto:productions@elevenlabs.io)

      .
    </Info>
  </Step>

  <Step title="Track your order progress">
    Head to the [Productions](https://elevenlabs.io/app/productions) page of your ElevenLabs account and click any order to open a side panel with more details.

    You'll also receive an email when your order is ready.

    <Frame background="subtle">
      ![Sidebar](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7febf81821dfd24da99d0d1ddc0c58ed66866a61ee9f849f75f1b150b02332bf/assets/images/productions/productions-sidebar-small.png)
    </Frame>
  </Step>

  <Step title="View and download your completed assets and invoices">
    Open a completed Production and click the *View* button to open a read only copy. You can also download an invoice for your order by clicking the link next to *Details*.

    To export your completed assets, use the export menu in the sidebar or inside the read only copy.

    <Frame background="subtle">
      ![Export menu](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7ba125ad4d96992a9a078b275cc0b85e3a21f6d5ca6bea1f36f775c10c98856b/assets/images/productions/productions-export.gif)
    </Frame>
  </Step>

  <Step title="Organize your assets into folders">
    Productions has a folder system to help you organize your assets. Click *New folder* to create a new folder. Click *Manage* and use the *Move to Folder* option in the toolbar to nest folders inside other folders.

    <Frame background="subtle">
      ![Folders](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/660a49d56be4c962ae583498654f83a1342edf8904bd2d35b806a9cd4e01373e/assets/images/productions/productions-folders.png)
    </Frame>
  </Step>
</Steps>

## Enterprise

We offer a white glove service to enterprise customers that can make volume commitments, including:

* Discounted per minute rates on each of our services
* Expedited turnaround times
* Advanced pre and post-processing services

Email us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io) or [contact sales](https://elevenlabs.io/contact-sales) to learn more.

## FAQ

<AccordionGroup>
  <Accordion title="How much does it cost?">
    All Productions prices are presented to you in USD (\$) per minute of source audio. Exact prices depend on the type of asset you want to order (transcript, subtitles, dub, etc.), the source and target languages, and any custom style guide options you choose.

    We **always** show you up front how much a Production will cost before asking you to confirm and complete a checkout process.
  </Accordion>

  <Accordion title="What languages do you support?">
    We currently support the following languages for Productions jobs, both source and target:

    * Arabic
    * English
    * French
    * German
    * Hindi
    * Italian
    * Portuguese
    * Russian
    * Spanish
    * Turkish
    * Ukrainian

    We're working hard to expand our language coverage quickly and will update this list as new languages become available.
  </Accordion>

  <Accordion title="What if I'm not happy with the result?">
    You can leave feedback on a completed production by opening it (use the *View* option in the sidebar) and clicking the *Feedback* button.
  </Accordion>

  <Accordion title="Can I make changes once I receive the final version?">
    No. You can export a completed Production and make changes off platform. We plan to add support for this soon.
  </Accordion>

  <Accordion title="Are Productions jobs really done by humans?">
    Yes, Productions is powered by a network of expert linguists and localization professionals
    vetted and trained by ElevenLabs.

    If you'd like to join our Producer network, please check the Productions openings on our [Careers page](https://elevenlabs.io/careers)
  </Accordion>

  <Accordion title="I have specific requirements I'd like to discuss – is that possible?">
    Yes, please contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).
  </Accordion>
</AccordionGroup>


# Transcripts

> Human-edited transcripts from ElevenLabs Productions

## General

Transcripts ordered from Productions are reviewed and corrected by native speakers for maximum accuracy.
We offer 2 types of human transcripts:

| **Option**                 | **When to use it**                          | **Description**                                                                                                                                               |
| -------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Non‑verbatim ("clean")** | Podcasts, webinars, marketing, personal use | Removes filler words, stutters, audio event tags for smoother reading. Focuses on transcribing the core meaning. Most suitable for the majority of use-cases. |
| **Verbatim**               | Legal, research                             | Attempts to capture *exactly* what is said, including all filler words, stutters and audio event tags.                                                        |

* For a more detailed breakdown of non-verbatim vs. verbatim transcription options, please see the [**Style guides**](#style-guides) section below.
* For more information about other Productions services, please see the [Overview](/docs/creative-platform/services/productions/overview) page.

## How it works

<Steps>
  <Step title="Order transcript">
    <AccordionGroup>
      <Accordion title="Transcribing new files">
        ### Productions page

        The easiest way to order a new transcript from Productions is from the [Productions](https://elevenlabs.io/app/productions) page in your ElevenLabs account.

        <Frame background="subtle">
          <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cd072dfc01c9b277960c0583a3900ca963ee0ca766f204f5fac602117f5a8174/assets/images/productions/productions-home.png" alt="Productions Home" />
        </Frame>

        ### Speech to Text Order Dialog

        You can also select the *Human Transcript* option in the [Speech to Text](/docs/overview/capabilities/speech-to-text) order dialog.

        <Frame background="subtle">
          <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1d18c451ce48b05fb9943a11707e86cd7a8c883b30e7557551f1bdccc05851a9/assets/images/productions/productions-stt-dialog.png" alt="Productions STT Dialog" />
        </Frame>
      </Accordion>

      <Accordion title="Starting from an existing transcript">
        Open an existing transcript and click the *Get human review* button to create a new Productions order for that transcript.

        <Frame background="subtle">
          <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b25a0e08ad610f29b352c4cf9a1ef8f29061487c61f51de7c5c0b2cfb0533863/assets/images/productions/productions-get-human-review.png" alt="Productions Get Human Review" />
        </Frame>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Export transcript">
    You will receive an email notification when your transcript is ready and see it marked as 'Done' on your Productions page.

    <AccordionGroup>
      <Accordion title="Quick export">
        Open a transcript on your [Productions](https://elevenlabs.io/app/productions) page and click the three dots, then the *Export* button.

        <Frame background="subtle">
          ![Export menu](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7ba125ad4d96992a9a078b275cc0b85e3a21f6d5ca6bea1f36f775c10c98856b/assets/images/productions/productions-export.gif)
        </Frame>
      </Accordion>

      <Accordion title="Export from viewer">
        Open a transcript on your [Productions](https://elevenlabs.io/app/productions) page and click the *View* icon to open the transcript viewer.

        <Frame background="subtle">
          ![Viewer export menu](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f28752b990b7c64764c7c73e4be3e3e7dc24e10b3a51d4e445cf70a47dea5f19/assets/images/productions/productions-viewer-export.gif)
        </Frame>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Pricing

Our transcription pricing depends on several factors, including languages, transcription type (verbatim vs non-verbatim), and content complexity. [Talk to sales](https://elevenlabs.io/contact-sales) to discuss your specific needs and get a custom quote.

## SLAs / Delivery Time

We aim to deliver all transcripts **within 48 hours.** If you are an enterprise interested in achieving quicker turnaround times, please contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).

## Style guides

When ordering a Productions transcript, you will see the option to activate 'Verbatim' mode. Please read the breakdown below for more information about this option.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fdf172c15645a4cfe48e59cb436adcaae7ff6c16979374e358d4ce56071250a9/assets/images/productions/productions-style-guide.png" alt="Productions Style Guide" />
</Frame>

<AccordionGroup>
  <Accordion title="Non-verbatim">
    Non-verbatim transcription, also called *clean* or *intelligent verbatim*, focuses on clarity and readability. Unlike verbatim transcriptions, it removes unnecessary elements like filler words, stutters, and irrelevant sounds while preserving the speaker’s message.

    <Info>
      This is the default option for Productions transcriptions. Unless you explicitly select 'Verbatim' mode, we will deliver a non-verbatim transcript.
    </Info>

    What gets left out in non-verbatim transcripts:

    * **Filler words and verbal tics** like “um,” “like,” “you know,” or “I mean”
    * **Repetitions** including intentional and unintentional (e.g. stuttering)
    * **Audio event tags,** including non-verbal sounds like \[coughing] or \[throat clearing] as well as environmental sounds like \[dog barking]
    * **Slang or incorrect grammar** (e.g. ‘ain’t’ → ‘is not’)
  </Accordion>

  <Accordion title="Verbatim">
    In verbatim transcription, the goal is to capture ***everything that can be heard,***, meaning:

    * All detailed verbal elements: stutters, repetitions, etc
    * All non-verbal elements like human sounds (\[cough]) and environmental sounds (\[dog barking])
  </Accordion>

  <Accordion title="Non-verbatim vs. verbatim">
    The following table provides a comprehensive breakdown of our non-verbatim vs. verbatim transcription services.

    | **Feature**                 | **Verbatim Transcription**                                                                  | **Verbatim Example**                                         | **Non-Verbatim (Clean) Transcription**                                                                                                                                                                                                                                  | **Non-Verbatim Example**                                                           |
    | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
    | **Filler words**            | All filler words are included exactly as spoken.                                            | "So, um, I was like, you know, maybe we should wait."        | Filler words like "um," "like," "you know" are removed.                                                                                                                                                                                                                 | "I was thinking maybe we should wait."                                             |
    | **Stutters**                | Stutters and repeated syllables are transcribed with hyphens.                               | "I-I-I don't know what to say."                              | Stutters are removed for smoother reading.                                                                                                                                                                                                                              | "I don't know what to say."                                                        |
    | **Repetitions**             | Repeated words are retained even when unintentional.                                        | "She, she, she told me not to come."                         | Unintentional repetitions are removed.                                                                                                                                                                                                                                  | "She told me not to come."                                                         |
    | **False Starts**            | False starts are included using double hyphens.                                             | "I was going to—no, actually—let's wait."                    | False starts are removed unless they show meaningful hesitation.                                                                                                                                                                                                        | "Let's wait."                                                                      |
    | **Interruptions**           | Speaker interruptions are marked with a single hyphen.                                      | Speaker 1: "Did you see—" Speaker 2: "Yes, I did."           | Interruptions are simplified or smoothed.                                                                                                                                                                                                                               | Speaker 1: "Did you see it?" Speaker 2: "Yes, I did."                              |
    | **Informal Contractions**   | Informal speech is preserved as spoken.                                                     | "She was gonna go, but y'all called."                        | Standard grammar should be used for clarity, outside of exceptions. Please refer to your [language style guide](https://www.notion.so/Transcription-1e5506eacaa280678598cf06de67802d?pvs=21) to know which contractions to keep vs. when to resort to standard grammar. | "She was going to go, but you all called."                                         |
    | **Emphasized Words**        | Elongated pronunciations are reflected with extended spelling.                              | "That was amaaazing!"                                        | Standard spelling is used.                                                                                                                                                                                                                                              | "That was amazing!"                                                                |
    | **Interjections**           | Interjections and vocal expressions are included.                                           | "Ugh, this is terrible. Wow, I can't believe it!"            | Only meaningful interjections are retained.                                                                                                                                                                                                                             | "This is terrible. Wow, I can't believe it!"                                       |
    | **Swear Words**             | Swear words are fully transcribed.                                                          | "Fuck this, I'm not going."                                  | Swear words should be fully transcribed, unless indicated otherwise.                                                                                                                                                                                                    | "Fuck this, I'm not going."                                                        |
    | **Pronunciation Mistakes**  | Mispronounced words are corrected.                                                          | **Example (spoken):** "ecsetera" **Transcribed:** "etcetera" | Mispronounced words are corrected here as well.                                                                                                                                                                                                                         | **Example (spoken):** "ecsetera" **Transcribed:** "etcetera"                       |
    | **Non-verbal human sounds** | Human non-verbal sounds like \[laughing], \[sighing], \[swallowing] are transcribed inline. | "I—\[sighs]—don't know."                                     | Most non-verbal sounds are excluded unless they impact meaning.                                                                                                                                                                                                         | "I don't know."                                                                    |
    | **Environmental Sounds**    | Environmental sounds are described in square brackets.                                      | "\[door slams], \[birds chirping], \[phone buzzes]"          | Omit unless essential to meaning. **Include if:** 1. The sound impacts emotion or meaning 2. The sound is directly referenced by the speaker                                                                                                                            | "What was that noise? \[dog barking]" "Hang on, I hear something \[door slamming]" |
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What if I'm not happy with the result?">
    You can leave feedback on a completed transcript by clicking the three dots (⋯) next to your deliverable and selecting *Feedback*.
  </Accordion>

  <Accordion title="Can I make changes once I receive the final version?">
    No. You can export a completed transcript and make changes off platform. We plan to add support for this soon.
  </Accordion>
</AccordionGroup>


# Subtitles

> Human-edited captions and subtitles from ElevenLabs Productions

## General

Subtitles and captions ordered from Productions are reviewed and edited by native speakers for maximum accuracy and accessibility. We offer both subtitles and captions to meet your specific needs.

* For more information about other Productions services, please see the [Overview](/docs/creative-platform/services/productions/overview) page.

## Captions vs. subtitles

Captions and subtitles serve different audiences and purposes, although they both display text on screen.

* **Captions** transcribe spoken dialogue and include SDH<a href="#sdh-footnote" aria-label="SDH footnote"><sup>1</sup></a> by default. They are not translated.

* **Subtitles** translate spoken dialogue for viewers who do not understand the source language; SDH<a href="#sdh-footnote" aria-label="SDH footnote"><sup>1</sup></a> can by included upon request.

<div>
  |                        | **Captions**                                | **Subtitles**                                  |
  | ---------------------- | ------------------------------------------- | ---------------------------------------------- |
  | Content                | Spoken dialogue                             | Spoken dialogue                                |
  | Translation            | No                                          | Yes                                            |
  | Non‑speech sounds      | Included by default                         | Not included by default                        |
  | Music cues             | Included by default                         | Not included by default                        |
  | Speaker identification | Included by default                         | Not included by default                        |
  | Typical audience       | Deaf/Hard of Hearing; same-language viewers | Hearing viewers who don’t know source language |
</div>

<div id="sdh-footnote">
  <sup>1</sup> SDH (Subtitles for the Deaf and Hard of Hearing) adds essential non‑speech audio cues
  (e.g., \[door slams], ♪ music ♪) and speaker identification. Included by default in captions;
  optional for subtitles.
</div>

## How it works

<Steps>
  <Step title="Order subtitles and captions">
    The easiest way to order new subtitles from Productions is from the
    [Productions](https://elevenlabs.io/app/productions) page in your ElevenLabs account.

    <Frame background="subtle">
      ![Productions Home Page](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cd072dfc01c9b277960c0583a3900ca963ee0ca766f204f5fac602117f5a8174/assets/images/productions/productions-home.png)
    </Frame>
  </Step>

  <Step title="Export subtitles and captions">
    You will receive an email notification when your subtitles are ready and see them marked as
    'Done' on your Productions page. Export your completed subtitles in SRT format.
  </Step>
</Steps>

## Pricing

Our subtitles and captions pricing depends on several factors, including languages, content type, and services included. [Talk to sales](https://elevenlabs.io/contact-sales) to discuss your specific needs and get a custom quote.

## SLAs / Delivery time

We aim to deliver all subtitles and captions **within 48-72 hours.** If you are an enterprise interested in achieving quicker turnaround times, please contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).

## FAQ

<AccordionGroup>
  <Accordion title="What file formats do you support for subtitles?">
    We support SRT format for subtitle exports.
  </Accordion>

  <Accordion title="What if I'm not happy with the result?">
    You can leave feedback on a completed subtitle project by clicking the three dots (⋯) next to your deliverable and selecting *Feedback*.
  </Accordion>

  <Accordion title="Can I make changes once I receive the final version?">
    No. You can export completed subtitles and make changes off platform. We plan to add support for this soon.
  </Accordion>
</AccordionGroup>


# Dubbing

> Human-edited dubbing services from ElevenLabs Productions

## General

With our Productions dubbing offering, localize your content to reach any audience in the world. Share your video, source language, and destination language, and receive a fully dubbed video which is natural-sounding and production-ready.

* For more information about other Productions services, please see the [Overview](/docs/creative-platform/services/productions/overview) page.

## How it works

<Steps>
  <Step title="Order a dub">
    The easiest way to order a dub from Productions is through the [Productions](https://elevenlabs.io/app/productions) page in your ElevenLabs account. Simply share:

    * **Your video file** (MP4, MOV, AVI, MKV)
    * **Source language** (e.g., English)
    * **Target language** (e.g., Spanish, Hindi, Arabic)

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cd072dfc01c9b277960c0583a3900ca963ee0ca766f204f5fac602117f5a8174/assets/images/productions/productions-home.png" alt="Productions Home" />
    </Frame>
  </Step>

  <Step title="Processing">
    Using proprietary AI models with human-in-the-loop craftsmanship, we:

    * Accurately **transcribe** the source audio
    * **Translate** into the requested target language with contextual accuracy
    * **Generate** synthetic voices matched to speaker identity and tone, or use custom voices
    * **Synchronize** dubbed speech with the original video timing
  </Step>

  <Step title="Order delivery">
    You'll receive a fully dubbed video with multiple export options: MP4 Video (default), AAC Audio, MP3 Audio, WAV Audio, Audio Tracks or Clips (Zip File), AAF (Timeline Data), SRT Captions, TXT Transcript.

    **To export your completed dub:**

    1. Access your order in the [Productions](https://elevenlabs.io/app/productions) page
    2. Click **View** to open the project
    3. Once inside the project, select your desired format from the export options
    4. Choose whether to normalize the audio (optional)
    5. Click **Export** to generate the file
    6. You can then view or download your exported dub
  </Step>
</Steps>

## Behind the scenes

We follow a strict workflow to deliver consistent, natural-sounding dubs:

* **Transcription**: highly accurate transcription and speaker allocation.
* **Translation**: thorough review of translation accuracy by a native speaker, and edits to make the voice-over sound as natural as possible.
* **Voice selection**: we carefully pick the right voice for your dub, or use the voices you've shared with us.
* **Pacing**: we regenerate segments or edit the transcription to ensure the best possible pacing on each segment.
* **Quality control**: each dub goes through a checklist to ensure accuracy, consistency, and natural delivery.

## Pricing

Our dubbing prices depend on several factors, including languages, type of content, and services included. [Talk to sales](https://elevenlabs.io/contact-sales) to discuss your specific needs and get a custom quote.

## SLAs / Delivery time

We aim to deliver all dubbing projects **within 7 business days.** If you are an enterprise interested in achieving quicker turnaround times, please contact us at [productions@elevenlabs.io](mailto:productions@elevenlabs.io).

## FAQ

<AccordionGroup>
  <Accordion title="What video formats do you support?">
    We support MP4, MOV, AVI, and MKV formats for video uploads. The final dubbed video is delivered in MP4 format by default.
  </Accordion>

  <Accordion title="What if I'm not happy with the result?">
    You can leave feedback on a completed dub by clicking the three dots (⋯) next to your deliverable and selecting *Feedback*.
  </Accordion>

  <Accordion title="Can I make changes once I receive the final version?">
    Yes, you can open the project in Dubbing Studio and make changes to refine the output.
  </Accordion>

  <Accordion title="Do you provide lip sync?">
    We do our best to match timing and visible mouth movements, but perfect lip sync is not guaranteed and may vary depending on the content.
  </Accordion>
</AccordionGroup>


# Troubleshooting

> Explore common issues and solutions.

Our models are non-deterministic, meaning outputs can vary based on inputs. While we strive to enhance predictability, some variability is inherent. This guide outlines common issues and preventive measures.

## General

<AccordionGroup>
  <Accordion title="Inconsistencies in volume and quality">
    If the generated voice output varies in volume or tone, it is often due to inconsistencies in the voice clone training audio.

    * **Apply compression**: Compress the training audio to reduce dynamic range and ensure consistent audio. Aim for a RMS between -23 dB and -18 dB and the true peak below -3 dB.
    * **Background noise**: Ensure the training audio contains only the voice you want to clone — no music, noise, or pops. Background noise, sudden bursts of energy or consistent low-frequency energy can make the AI less stable.
    * **Speaker consistency**: Ensure the speaker maintains a consistent distance from the microphone and avoids whispering or shouting. Variations can lead to inconsistent volume or tonality.
    * **Audio length**:
      * **Instant Voice Cloning**: Use 1–2 minutes of consistent audio. Consistency in tonality, performance, accent, and quality is crucial.
      * **Professional Voice Cloning**: Use at least 30 minutes, ideally 2+ hours, of consistent audio for best results.

    To minimize issues, consider breaking your text into smaller segments. This approach helps maintain consistent volume and reduces degradation over longer audio generations. Utilize our Studio feature to generate several smaller audio segments simultaneously, ensuring better quality and consistency.

    <Note>
      Refer to our guides for optimizing Instant and Professional Voice Clones for best practices and
      advice.
    </Note>
  </Accordion>

  <Accordion title="Mispronunciation">
    The multilingual models may rarely mispronounce certain words, even in English. This issue appears to be somewhat arbitrary but seems to be voice and text-dependent. It occurs more frequently with certain voices and text, especially when using words that also appear in other languages.

    * **Use Studio**: This feature helps minimize mispronunciation issues, which are more prevalent in longer text sections when using Speech Synthesis. While it won't completely eliminate the problem, it can help avoid it and make it easier to regenerate specific sections without redoing the entire text.
    * **Properly cloned voices**: Similar to addressing inconsistency issues, using a properly cloned voice in the desired languages can help reduce mispronunciation.
    * **Specify pronunciation**: When using our Studio feature, consider specifying the pronunciation of certain words, such as character names and brand names, or how acronyms should be read. For more information, refer to the Pronunciation Dictionary section of our guide to Studio.
  </Accordion>

  <Accordion title="Language switching and accent drift">
    The AI can sometimes switch languages or accents throughout a single generation, especially if that generation is longer in length. This issue is similar to the mispronunciation problem and is something we are actively working to improve.

    * **Use properly cloned voices**: Using an Instant Voice Clone or a Professional Voice Clone trained on high-quality, consistent audio in the desired language can help mitigate this issue. Pairing this with the Studio feature can further enhance stability.
    * **Understand voice limitations**: Default and generated voices are primarily English and may carry an English accent when used for other languages. Cloning a voice that speaks the target language with the desired accent provides the AI with better context, reducing the likelihood of language switching.
    * **Language selection**: Currently, the AI determines the language based on the input text. Writing in the desired language is crucial, especially when using pre-made voices that are English-based, as they may introduce an English accent.
    * **Optimal text length**: The AI tends to maintain a consistent accent over shorter text segments. For best results, keep text generations under 800-900 characters when using Text-to-Speech. The Studio workflow can help manage longer texts by breaking them into smaller, more manageable segments.
  </Accordion>

  <Accordion title="Mispronounced numbers, symbols or acronyms">
    The models may mispronounce certain numbers, symbols and acronyms. For example, the numbers "1, 2, 3" might be pronounced as "one," "two," "three" in English. To ensure correct pronunciation in another language, write them out phonetically or in words as you want them to be spoken.

    * **Example**: For the number "1" to be pronounced in French, write "un."
    * **Symbols**: Specify how symbols should be read, e.g., "\$" as "dollar" or "euro."
    * **Acronyms**: Spell out acronyms phonetically.
  </Accordion>

  <Accordion title="Corrupt speech">
    Corrupt speech is a rare issue where the model generates muffled or distorted audio. This occurs
    unpredictably, and we have not identified a cause. If encountered, regenerate the section to
    resolve the issue.
  </Accordion>

  <Accordion title="Audio degradation over longer generations">
    Audio quality may degrade during extended text-to-speech conversions, especially with the Multilingual v1 model. To mitigate this, break text into sections under 800 characters.

    * **Voice Selection**: Some voices are more susceptible to degradation. Use high-quality samples for cloned voices to minimize artifacts.
    * **Stability and Similarity**: Adjust these settings to influence voice behavior and artifact prominence. Hover over each setting for more details.
  </Accordion>

  <Accordion title="Style exaggeration">
    For some voices, this voice setting can lead to instability, including inconsistent speed,
    mispronunciation and the addition of extra sounds. We recommend keeping this setting at 0,
    especially if you find you are experiencing these issues in your generated audio.
  </Accordion>
</AccordionGroup>

## Studio (formerly Projects)

<AccordionGroup>
  <Accordion title="File imports">
    The import function attempts to import the file you provide to the website. Given the variability in website structures and book formatting, including images, always verify the import for accuracy.

    * **Chapter images**: If a book's chapters start with an image as the first letter, the AI may not recognize the letter. Manually add the letter to each chapter.
    * **Paragraph structure**: If text imports as a single long paragraph instead of following the original book's structure, it may not function correctly. Ensure the text maintains its original line breaks. If issues persist, try copying and pasting. If this fails, the text format may need conversion or rewriting.
    * **Preferred format**: EPUB is the recommended file format for creating a project in Studio. A well-structured EPUB will automatically split each chapter in Studio, facilitating navigation. Ensure each chapter heading is formatted as "Heading 1" for proper recognition.

    <Note>
      Always double-check imported content for accuracy and structure.
    </Note>
  </Accordion>

  <Accordion title="Glitches between paragraphs">
    Occasionally, glitches or sharp breaths may occur between paragraphs. This is rare and differs
    from standard Text to Speech issues. If encountered, regenerate the preceding paragraph, as the
    problem often originates there.
  </Accordion>
</AccordionGroup>

<Note>
  If an issue persists after following this troubleshooting guide, please [contact our support
  team](https://help.elevenlabs.io/hc/en-us/requests/new?ticket_form_id=13145996177937).
</Note>


# ElevenAgents

> Learn how to build, launch, and scale agents with ElevenLabs.

Agents accomplish tasks through natural dialogue - from quick requests to complex, open-ended workflows. ElevenLabs provides voice-rich, expressive models, developer tools for building multimodal agents, and tools to monitor and evaluate agent performance at scale.

<div id="agents-cards">
  <a href="/docs/agents-platform/build/overview">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b01da89ad7994300673d0932d321cd0f53fe727b6210e6c1f00e765e498f8722/assets/images/agents/agents-overview-build.png" alt="" />
    </div>

    <div>
      <h3>
        Configure
      </h3>

      <p>
        Configure multimodal agents with our developer toolkit, dashboard, or visual workflow
        builder
      </p>
    </div>
  </a>

  <a href="/docs/agents-platform/integrate/overview">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/17a81505a62493491ead763b307b1e854825a0da67ab1a1d86b41b57ad87bc73/assets/images/agents/agents-overview-integrate.png" alt="" />
    </div>

    <div>
      <h3>
        Deploy
      </h3>

      <p>
        Integrate multimodal agents across telephony systems, web, and mobile
      </p>
    </div>
  </a>

  <a href="/docs/agents-platform/operate/overview">
    <div>
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3790a000d203429c852cd4be74f2635ea41222f31b0edb53ae760c61e4a0f07d/assets/images/agents/agents-overview-operate.png" alt="" />

      <svg fill="none" stroke="currentColor" strokeWidth="1.5" viewBox="0 0 24 24">
        <path strokeLinecap="round" strokeLinejoin="round" d="M3 13.125C3 12.504 3.504 12 4.125 12h2.25c.621 0 1.125.504 1.125 1.125v6.75C7.5 20.496 6.996 21 6.375 21h-2.25A1.125 1.125 0 013 19.875v-6.75zM9.75 8.625c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125v11.25c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 01-1.125-1.125V8.625zM16.5 4.125c0-.621.504-1.125 1.125-1.125h2.25C20.496 3 21 3.504 21 4.125v15.75c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 01-1.125-1.125V4.125z" />
      </svg>
    </div>

    <div>
      <h3>
        Monitor
      </h3>

      <p>
        Evaluate agent performance with built-in testing, evals, and analytics
      </p>
    </div>
  </a>
</div>

## Platform capabilities

From design to deployment to optimization, ElevenLabs provides everything you need to build agents at scale.

### Design and configure

| Goal                          | Guide                                                                      | Description                                                            |
| ----------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Create conversation workflows | [Workflows](/docs/agents-platform/customization/agent-workflows)           | Build multi-step workflows with visual workflow builder                |
| Write system prompts          | [System prompt](/docs/agents-platform/best-practices/prompting-guide)      | Learn best practices for crafting effective agent prompts              |
| Select language model         | [Models](/docs/agents-platform/customization/llm)                          | Choose from supported LLMs or bring your own custom model              |
| Control conversation flow     | [Conversation flow](/docs/agents-platform/customization/conversation-flow) | Configure turn-taking, interruptions, and timeout settings             |
| Configure voice & language    | [Voice & language](/docs/agents-platform/customization/voice)              | Select from 5k+ voices across 31 languages with customization options  |
| Add knowledge to agent        | [Knowledge base](/docs/agents-platform/customization/knowledge-base)       | Upload documents and enable RAG for grounded responses                 |
| Connect tools                 | [Tools](/docs/agents-platform/customization/tools)                         | Enable agents to call clients & APIs to perform actions                |
| Personalize each conversation | [Personalization](/docs/agents-platform/customization/personalization)     | Use dynamic variables and overrides for per-conversation customization |
| Secure agent access           | [Authentication](/docs/agents-platform/customization/authentication)       | Implement custom authentication for protected agent access             |

### Connect and deploy

| Goal                        | Guide                                                                               | Description                                                        |
| --------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Build with React components | [ElevenLabs UI](https://ui.elevenlabs.io)                                           | Pre-built components library for audio & agent apps (shadcn-based) |
| Embed widget in website     | [Widget](/docs/agents-platform/customization/widget)                                | Add a customizable web widget to any website                       |
| Build React web apps        | [React SDK](/docs/agents-platform/libraries/react)                                  | Voice-enabled React hooks and components                           |
| Build iOS apps              | [Swift SDK](/docs/agents-platform/libraries/swift)                                  | Native iOS SDK for voice agents                                    |
| Build Android apps          | [Kotlin SDK](/docs/agents-platform/libraries/kotlin)                                | Native Android SDK for voice agents                                |
| Build React Native apps     | [React Native SDK](/docs/agents-platform/libraries/react-native)                    | Cross-platform iOS and Android with React Native                   |
| Connect via SIP trunk       | [SIP trunk](/docs/agents-platform/phone-numbers/sip-trunking)                       | Integrate with existing telephony infrastructure                   |
| Make batch outbound calls   | [Batch calls](/docs/agents-platform/phone-numbers/batch-calls)                      | Trigger multiple calls programmatically                            |
| Use Twilio integration      | [Twilio](/docs/agents-platform/phone-numbers/twilio-integration/native-integration) | Native Twilio integration for phone calls                          |
| Build custom integrations   | [WebSocket API](/docs/agents-platform/libraries/web-sockets)                        | Low-level WebSocket protocol for custom implementations            |
| Receive real-time events    | [Events](/docs/agents-platform/customization/events)                                | Subscribe to conversation events and updates                       |

### Monitor and optimize

| Goal                         | Guide                                                                         | Description                                          |
| ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- |
| Test agent behavior          | [Testing](/docs/agents-platform/customization/agent-testing)                  | Create and run automated tests for your agents       |
| Analyze conversation quality | [Conversation analysis](/docs/agents-platform/customization/agent-analysis)   | Extract insights and evaluate conversation outcomes  |
| Track metrics & analytics    | [Analytics](/docs/agents-platform/dashboard)                                  | Monitor performance metrics and conversation history |
| Configure data retention     | [Privacy](/docs/agents-platform/customization/privacy)                        | Set retention policies for conversations and audio   |
| Reduce LLM costs             | [Cost optimization](/docs/agents-platform/customization/llm/optimizing-costs) | Monitor and optimize language model expenses         |

## Architecture

ElevenAgents coordinates 4 core components:

1. A fine-tuned Speech to Text (ASR) model for speech recognition
2. Your choice of language model or [custom](/docs/agents-platform/customization/llm/custom-llm) LLM
3. A low-latency Text to Speech (TTS) model across 5k+ voices and 31 languages
4. A proprietary turn-taking model that handles conversation timing

<Card title="Quickstart" href="/docs/agents-platform/quickstart">
  Build your first agent in 5 minutes
</Card>


# Quickstart

> Build your first conversational agent in as little as 5 minutes.

In this guide, you'll learn how to create your first conversational agent. This will serve as a foundation for building conversational workflows tailored to your business use cases.

## Getting started

ElevenLabs Agents are managed either through the [ElevenAgents dashboard](https://elevenlabs.io/app/agents), the [ElevenLabs API](/docs/api-reference/introduction) or the [Agents CLI](/docs/agents-platform/operate/cli).

<Frame caption="The assistant at the bottom right corner of this page is an example of an ElevenLabs agent, capable of answering questions about ElevenLabs, navigating pages & taking you to external resources." background="subtle">
  ![ElevenLabs Agents](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb/assets/images/conversational-ai/widget.png)
</Frame>

## Creating your first agent

In this quickstart guide we'll start by creating an agent via the API or the web dashboard. Next we'll test the agent, either by embedding it in your website or via the ElevenLabs dashboard.

<Tabs>
  <Tab title="Build an agent via the web dashboard">
    In this guide, we'll create a conversational support assistant capable of answering questions about your product, documentation, or service. This assistant can be embedded into your website or app to provide real-time support to your customers.

    <Frame caption="The assistant at the bottom right corner of this page is capable of answering questions about ElevenLabs, navigating pages & taking you to external resources." background="subtle">
      ![ElevenLabs Agents](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb/assets/images/conversational-ai/widget.png)
    </Frame>

    <Steps>
      <Step title="Sign in to ElevenLabs">
        Go to [elevenlabs.io](https://elevenlabs.io/app/sign-up) and sign in to or create your account.
      </Step>

      <Step title="Create a new assistant">
        In the **ElevenLabs Dashboard**, create a new assistant by entering a name and selecting the `Blank template` option.

        <Frame caption="Creating a new assistant" background="subtle">
          ![Dashboard](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/61b0e1df291ea587a8ff3e116579a47f66d48c74b24f44cfcd4804a568eb0a9d/assets/images/conversational-ai/assistant-create-flow.gif)
        </Frame>
      </Step>

      <Step title="Configure the assistant behavior">
        Go to the **Agent** tab to configure the assistant's behavior. Set the following:

        <Steps>
          <Step title="First message">
            This is the first message the assistant will speak out loud when a user starts a conversation.

            ```plaintext First message
            Hi, this is Alexis from <company name> support. How can I help you today?
            ```
          </Step>

          <Step title="System prompt">
            This prompt guides the assistant's behavior, tasks, and personality.

            Customize the following example with your company details:

            ```plaintext System prompt
            You are a friendly and efficient virtual assistant for [Your Company Name]. Your role is to assist customers by answering questions about the company's products, services, and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

            Tasks:
            - Answer Questions: Provide clear and concise answers based on the available information.
            - Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

            Guidelines:
            - Maintain a friendly and professional tone throughout the conversation.
            - Be patient and attentive to the customer's needs.
            - If unsure about any information, politely ask the customer to repeat or clarify.
            - Avoid discussing topics unrelated to the company's products or services.
            - Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
            ```
          </Step>
        </Steps>
      </Step>

      <Step title="Add a knowledge base">
        Go to the **Knowledge Base** section to provide your assistant with context about your business.

        This is where you can upload relevant documents & links to external resources:

        * Include documentation, FAQs, and other resources to help the assistant respond to customer inquiries.
        * Keep the knowledge base up-to-date to ensure the assistant provides accurate and current information.
      </Step>
    </Steps>

    Next we'll configure the voice for your assistant.

    <Steps>
      <Step title="Select a voice">
        In the **Voice** tab, choose a voice that best matches your assistant from the [voice library](https://elevenlabs.io/voice-library):

        <Frame background="subtle">
          ![Voice settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/14aad328f468daafa9ec95d3b7a55489a8cb1a34869368020e05b207c9b0360a/assets/images/conversational-ai/voice-settings.jpg)
        </Frame>

        <Note>
           Using higher quality voices, models, and LLMs may increase response time. For an optimal customer experience, balance quality and latency based on your assistant's expected use case.
        </Note>
      </Step>

      <Step title="Testing your assistant">
        Press the **Test AI agent** button and try conversing with your assistant.
      </Step>
    </Steps>

    Configure evaluation criteria and data collection to analyze conversations and improve your assistant's performance.

    <Steps>
      <Step title="Configure evaluation criteria">
        Navigate to the **Analysis** tab in your assistant's settings to define custom criteria for evaluating conversations.

        <Frame background="subtle">
          ![Analysis settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fee8bc444d5436c71eae3829b9ec8d5cdb6a57c4d4efe6483d7bfed2b066e438/assets/images/conversational-ai/analysis-settings.png)
        </Frame>

        Every conversation transcript is passed to the LLM to verify if specific goals were met. Results will either be `success`, `failure`, or `unknown`, along with a rationale explaining the chosen result.

        Let's add an evaluation criteria with the name `solved_user_inquiry`:

        ```plaintext Prompt
        The assistant was able to answer all of the queries or redirect them to a relevant support channel.

        Success Criteria:
        - All user queries were answered satisfactorily.
        - The user was redirected to a relevant support channel if needed.
        ```
      </Step>

      <Step title="Configure data collection">
        In the **Data Collection** section, configure details to be extracted from each conversation.

        Click **Add item** and configure the following:

        1. **Data type:** Select "string"
        2. **Identifier:** Enter a unique identifier for this data point: `user_question`
        3. **Description:** Provide detailed instructions for the LLM about how to extract the specific data from the transcript:

        ```plaintext Prompt
        Extract the user's questions & inquiries from the conversation.
        ```

        <Tip>
          Test your assistant by posing as a customer. Ask questions, evaluate its responses, and tweak the prompts until you're happy with how it performs.
        </Tip>
      </Step>

      <Step title="View conversation history">
        View evaluation results and collected data for each conversation in the **Call history** tab.

        <Frame background="subtle">
          ![Conversation history](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fd517a080ba2c0d678c1ce34ea79afbd0dad764a19da43ca045a1c29b693ee48/assets/images/conversational-ai/transcript.jpg)
        </Frame>

        <Tip>
          Regularly review conversation history to identify common issues and patterns.
        </Tip>
      </Step>
    </Steps>

    The newly created agent can be tested in a variety of ways, but the quickest way is to use the [ElevenLabs dashboard](https://elevenlabs.io/app/agents).

    <Info>
      The web dashboard uses our [React SDK](/docs/agents-platform/libraries/react) under the hood to handle real-time conversations.
    </Info>

    If instead you want to quickly test the agent in your own website, you can use the Agent widget. Simply paste the following HTML snippet into your website, taking care to replace `agent-id` with the ID of your agent.

    ```html
    <elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Tab>

  <Tab title="Build an agent via the CLI">
    <Steps>
      <Step title="Install the CLI">
        ```bash
        npm install -g @elevenlabs/cli
        ```
      </Step>

      <Step title="Initialize a new project">
        ```bash
        elevenlabs agents init
        ```

        This creates the project structure with configuration directories and registry files.
      </Step>

      <Step title="Authenticate with ElevenLabs">
        [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you'll use to securely [use the CLI](/docs/api-reference/authentication).

        Then run the following command to authenticate with ElevenLabs:

        ```bash
        elevenlabs auth login
        ```

        Enter your ElevenLabs API key when prompted. The CLI will verify the key and store it securely.
      </Step>

      <Step title="Create the agent">
        Create your first agent using the assistant template:

        ```bash
        elevenlabs agents add "My Assistant" --template assistant
        ```
      </Step>

      <Step title="Push to ElevenLabs platform">
        ```bash
        elevenlabs agents push --agent "My Assistant"
        ```

        This uploads your local agent configuration to the ElevenLabs platform.
      </Step>

      <Step title="Test the agent">
        The newly created agent can be tested in a variety of ways, but the quickest way is to use the [ElevenLabs dashboard](https://elevenlabs.io/app/agents). From the dashboard, select your agent and click the **Test AI agent** button.

        <Info>
          The web dashboard uses our [React SDK](/docs/agents-platform/libraries/react) under the hood to handle real-time conversations.
        </Info>

        If instead you want to quickly test the agent in your own website, you can use the Agent widget. Use the CLI to generate the HTML snippet:

        ```bash
        elevenlabs agents widget "My Assistant"
        ```

        This will output the HTML snippet you can then paste directly into your website.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build an agent via the API">
    <Steps>
      <Step title="Create an API key">
        [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

        Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

        ```js title=".env"
        ELEVENLABS_API_KEY=<your_api_key_here>
        ```
      </Step>

      <Step title="Install the SDK">
        We'll also use the `dotenv` library to load our API key from an environment variable.

        <CodeBlocks>
          ```python
          pip install elevenlabs
          pip install python-dotenv
          ```

          ```typescript
          npm install @elevenlabs/elevenlabs-js
          npm install dotenv
          ```
        </CodeBlocks>
      </Step>

      <Step title="Create the agent">
        Create a new file named `create_agent.py` or `createAgent.mts`, depending on your language of choice and add the following code:

        <CodeBlocks>
          ```python maxLines=0
          from dotenv import load_dotenv
          from elevenlabs.client import ElevenLabs
          import os
          load_dotenv()

          elevenlabs = ElevenLabs(
              api_key=os.getenv("ELEVENLABS_API_KEY"),
          )

          prompt = """
          You are a friendly and efficient virtual assistant for [Your Company Name].
          Your role is to assist customers by answering questions about the company's products, services,
          and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

          Tasks:
          - Answer Questions: Provide clear and concise answers based on the available information.
          - Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

          Guidelines:
          - Maintain a friendly and professional tone throughout the conversation.
          - Be patient and attentive to the customer's needs.
          - If unsure about any information, politely ask the customer to repeat or clarify.
          - Avoid discussing topics unrelated to the company's products or services.
          - Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
          """

          response = elevenlabs.conversational_ai.agents.create(
              name="My voice agent",
              tags=["test"], # List of tags to help classify and filter the agent
              conversation_config={
                  "tts": {
                      "voice_id": "aMSt68OGf4xUZAnLpTU8",
                      "model_id": "eleven_flash_v2"
                  },
                  "agent": {
                      "first_message": "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
                      "prompt": {
                          "prompt": prompt,
                      }
                  }
              }
          )

          print("Agent created with ID:", response.agent_id)
          ```

          ```typescript maxLines=0
          import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
          import "dotenv/config";

          const elevenlabs = new ElevenLabsClient();

          const prompt = `
              You are a friendly and efficient virtual assistant for [Your Company Name].
              Your role is to assist customers by answering questions about the company's products, services,
              and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

              Tasks:
              - Answer Questions: Provide clear and concise answers based on the available information.
              - Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

              Guidelines:
              - Maintain a friendly and professional tone throughout the conversation.
              - Be patient and attentive to the customer's needs.
              - If unsure about any information, politely ask the customer to repeat or clarify.
              - Avoid discussing topics unrelated to the company's products or services.
              - Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
          `;

          const agent = await elevenlabs.conversationalAi.agents.create({
              name: "My voice agent",
              tags: ["test"], // List of tags to help classify and filter the agent
              conversationConfig: {
                  tts: {
                      voiceId: "aMSt68OGf4xUZAnLpTU8",
                      modelId: "eleven_flash_v2",
                  },
                  agent: {
                      firstMessage: "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
                      prompt: {
                          prompt,
                      }
                  },
              },
          });

          console.log(`Agent created with ID: ${agent.agentId}`);
          ```
        </CodeBlocks>

        <Note>
          The agent created above will have a `"test"` tag, this is useful to help classify and filter the agent. For example distinguishing between test agents and production agents.
        </Note>
      </Step>

      <Step title="Run the code">
        <CodeBlocks>
          ```python
          python create_agent.py
          ```

          ```typescript
          npx tsx createAgent.mts
          ```
        </CodeBlocks>

        The above will generate an agent with some baseline settings and print the ID of the agent to the console. We'll customize the agent in a subsequent step.
      </Step>

      <Step title="Test the agent">
        The newly created agent can be tested in a variety of ways, but the quickest way is to use the [ElevenLabs dashboard](https://elevenlabs.io/app/agents). From the dashboard, select your agent and click the **Test AI agent** button.

        <Info>
          The web dashboard uses our [React SDK](/docs/agents-platform/libraries/react) under the hood to handle real-time conversations.
        </Info>

        If instead you want to quickly test the agent in your own website, you can use the Agent widget. Simply paste the following HTML snippet into your website, taking care to replace `agent-id` with the ID of your agent.

        ```html
        <elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
        <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
        ```

        View the SDKs tab to learn how to embed the agent in your website or app using the provided SDKs.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next steps

As a follow up to this quickstart guide, you can make your agent more effective by integrating:

* [Knowledge bases](/docs/agents-platform/customization/knowledge-base) to equip it with domain-specific information.
* [Tools](/docs/agents-platform/customization/tools) to allow it to perform tasks on your behalf.
* [Authentication](/docs/agents-platform/customization/authentication) to restrict access to certain conversations.
* [Success evaluation](/docs/agents-platform/customization/agent-analysis/success-evaluation) to analyze conversations and improve its performance.
* [Data collection](/docs/agents-platform/customization/agent-analysis/data-collection) to collect data about conversations and improve its performance.
* [Conversation retention](/docs/agents-platform/customization/privacy/retention) to view conversation history and improve its performance.


# Build

> Design and configure conversational AI agents with powerful customization options.

The Build section covers everything you need to create sophisticated conversational agents, from defining their behavior and voice to connecting external tools and knowledge sources.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b01da89ad7994300673d0932d321cd0f53fe727b6210e6c1f00e765e498f8722/assets/images/agents/agents-overview-build.png" alt="Build your agent" />
</Frame>

### Design and configure

| Goal                          | Guide                                                                      | Description                                                            |
| ----------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Create conversation workflows | [Workflows](/docs/agents-platform/customization/agent-workflows)           | Build multi-step workflows with visual workflow builder                |
| Write system prompts          | [System prompt](/docs/agents-platform/best-practices/prompting-guide)      | Learn best practices for crafting effective agent prompts              |
| Select language model         | [Models](/docs/agents-platform/customization/llm)                          | Choose from supported LLMs or bring your own custom model              |
| Control conversation flow     | [Conversation flow](/docs/agents-platform/customization/conversation-flow) | Configure turn-taking, interruptions, and timeout settings             |
| Configure voice & language    | [Voice & language](/docs/agents-platform/customization/voice)              | Select from 5k+ voices across 31 languages with customization options  |
| Add knowledge to agent        | [Knowledge base](/docs/agents-platform/customization/knowledge-base)       | Upload documents and enable RAG for grounded responses                 |
| Connect tools                 | [Tools](/docs/agents-platform/customization/tools)                         | Enable agents to call clients & APIs to perform actions                |
| Personalize each conversation | [Personalization](/docs/agents-platform/customization/personalization)     | Use dynamic variables and overrides for per-conversation customization |
| Secure agent access           | [Authentication](/docs/agents-platform/customization/authentication)       | Implement custom authentication for protected agent access             |

## Core components

### Agent behavior

Control how your agent thinks and responds:

* **Workflows**: Visual workflow builder for complex conversation flows
* **System Prompt**: Define agent personality, tone, and capabilities
* **Models**: Choose from leading LLMs or bring your own
* **Conversation Flow**: Configure turn-taking, interruptions, and pacing

### Voice & language

Customize the agent's voice and language capabilities:

* **Voice Selection**: Choose from 5k+ professional voices
* **Multi-voice Support**: Use different voices within conversations
* **Language Support**: Deploy in 31+ languages
* **Voice Design**: Create custom voices from text descriptions

### Knowledge & tools

Extend agent capabilities with external data and actions:

* **Knowledge Base**: Upload documents to ground agent responses
* **Tools**: Connect to APIs and external services
* **MCP Integration**: Use Model Context Protocol tools
* **System Tools**: Built-in capabilities like call transfer and voicemail detection

### Personalization

Tailor each conversation to your users:

* **Dynamic Variables**: Inject runtime data into conversations
* **Overrides**: Customize agent behavior per interaction
* **Authentication**: Secure agent access with custom auth flows

## Next steps

<CardGroup cols={2}>
  <Card title="Workflows" href="/docs/agents-platform/customization/agent-workflows">
    Build visual conversation flows
  </Card>

  <Card title="System Prompt" href="/docs/agents-platform/best-practices/prompting-guide">
    Learn prompting best practices
  </Card>

  <Card title="Voice & Language" href="/docs/agents-platform/customization/voice">
    Configure voice settings
  </Card>

  <Card title="Knowledge Base" href="/docs/agents-platform/customization/knowledge-base">
    Add domain knowledge
  </Card>
</CardGroup>


# Prompting guide

> System design principles for production-grade conversational AI

## Introduction

Effective prompting transforms [ElevenLabs Agents](/docs/agents-platform/overview) from robotic to lifelike.

<Frame background="subtle">
  ![ElevenLabs Agents prompting guide](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/255df05f53675feaf54c765c4ee294fda00a7c14de1b02f155922012bf0a5433/assets/images/conversational-ai/prompting-guide.jpg)
</Frame>

A system prompt is the personality and policy blueprint of your AI agent. In enterprise use, it tends to be elaborate—defining the agent's role, goals, allowable tools, step-by-step instructions for certain tasks, and guardrails describing what the agent should not do. The way you structure this prompt directly impacts reliability.

<Note>
  The system prompt controls conversational behavior and response style, but does not control
  conversation flow mechanics like turn-taking, or agent settings like which languages an agent can
  speak. These aspects are handled at the platform level.
</Note>

<Frame background="subtle">
  ![Enterprise agent reliability
  framework](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/18c7dd3bf58a6715656d588834a278dbc1f368eaed2cbf91aeea3e977c2631ed/assets/images/conversational-ai/system-prompt-principles.png)
</Frame>

## Prompt engineering fundamentals

A system prompt is the personality and policy blueprint of your AI agent. In enterprise use, it tends to be elaborate—defining the agent's role, goals, allowable tools, step-by-step instructions for certain tasks, and guardrails describing what the agent should not do. The way you structure this prompt directly impacts reliability.

The following principles form the foundation of production-grade prompt engineering:

### Separate instructions into clean sections

Separating instructions into dedicated sections with markdown headings helps the model prioritize and interpret them correctly. Use whitespace and line breaks to separate instructions.

**Why this matters for reliability:** Models are tuned to pay extra attention to certain headings (especially `# Guardrails`), and clear section boundaries prevent instruction bleed where rules from one context affect another.

<CodeBlocks>
  ```mdx title="Less effective approach"
  You are a customer service agent. Be polite and helpful. Never share sensitive data. You can look up orders and process refunds. Always verify identity first. Keep responses under 3 sentences unless the user asks for details.
  ```

  ```mdx title="Recommended approach"
  # Personality

  You are a customer service agent for Acme Corp. You are polite, efficient, and solution-oriented.

  # Goal

  Help customers resolve issues quickly by looking up orders and processing refunds when appropriate.

  # Guardrails

  Never share sensitive customer data across conversations.
  Always verify customer identity before accessing account information.

  # Tone

  Keep responses concise (under 3 sentences) unless the user requests detailed explanations.
  ```
</CodeBlocks>

### Be as concise as possible

Keep every instruction short, clear, and action-based. Remove filler words and restate only what is essential for the model to act correctly.

**Why this matters for reliability:** Concise instructions reduce ambiguity and token usage. Every unnecessary word is a potential source of misinterpretation.

<CodeBlocks>
  ```mdx title="Less effective approach"
  # Tone

  When you're talking to customers, you should try to be really friendly and approachable, making sure that you're speaking in a way that feels natural and conversational, kind of like how you'd talk to a friend, but still maintaining a professional demeanor that represents the company well.
  ```

  ```mdx title="Recommended approach"
  # Tone

  Speak in a friendly, conversational manner while maintaining professionalism.
  ```
</CodeBlocks>

<Note>
  If you need the agent to maintain a specific tone, define it explicitly and concisely in the `#
    Personality` or `# Tone` section. Avoid repeating tone guidance throughout the prompt.
</Note>

### Emphasize critical instructions

Highlight critical steps by adding "This step is important" at the end of the line. Repeating the most important 1-2 instructions twice in the prompt can help reinforce them.

**Why this matters for reliability:** In complex prompts, models may prioritize recent context over earlier instructions. Emphasis and repetition ensure critical rules aren't overlooked.

<CodeBlocks>
  ```mdx title="Less effective approach"
  # Goal

  Verify customer identity before accessing their account.
  Look up order details and provide status updates.
  Process refund requests when eligible.
  ```

  ```mdx title="Recommended approach"
  # Goal

  Verify customer identity before accessing their account. This step is important.
  Look up order details and provide status updates.
  Process refund requests when eligible.

  # Guardrails

  Never access account information without verifying customer identity first. This step is important.
  ```
</CodeBlocks>

### Normalize inputs and outputs

Voice agents often misinterpret or misformat structured information such as emails, IDs, or record locators. To ensure accuracy, separate (or "normalize") how data is spoken to the user from how it is written when used in tools or APIs.

**Why this matters for reliability:** Text-to-speech models sometimes mispronounce symbols like "@" or "." naturally, for example when an agent speaks "[john@company.com](mailto:john@company.com)" directly. Normalizing to spoken format ("john at company dot com") creates natural, understandable speech while maintaining correct written format for tools.

<CodeBlocks>
  ```mdx title="Less effective approach"
  When collecting the customer's email, repeat it back to them exactly as they said it, then use it in the `lookupAccount` tool.
  ```

  ```mdx title="Recommended approach"
  # Character normalization

  When collecting structured data (emails, phone numbers, confirmation codes):

  **Spoken format** (to/from user):

  - Email: "john dot smith at company dot com"
  - Phone: "five five five... one two three... four five six seven"
  - Code: "A B C one two three"

  **Written format** (for tools/APIs):

  - Email: "john.smith@company.com"
  - Phone: "5551234567"
  - Code: "ABC123"

  Always collect data in spoken format, then convert to written format before passing to tools.

  ## Example normalization rules

  - "@" symbol → spoken as "at", written as "@"
  - "." symbol → spoken as "dot", written as "."
  - Numbers → spoken individually ("one two three"), written as digits ("123")
  - Spaces in codes → spoken with pauses ("A B C"), written without spaces ("ABC")
  ```
</CodeBlocks>

<Tip>
  Add character normalization rules to your system prompt when agents collect emails, phone numbers,
  confirmation codes, or other structured identifiers that will be passed to tools.
</Tip>

### Provide clear examples

Include examples in the prompt to illustrate how agents should behave, use tools, or format data. Large language models follow instructions more reliably when they have concrete examples to reference.

**Why this matters for reliability:** Examples reduce ambiguity and provide a reference pattern. They're especially valuable for complex formatting, multi-step processes, and edge cases.

<CodeBlocks>
  ```mdx title="Less effective approach"
  When a customer provides a confirmation code, make sure to format it correctly before looking it up.
  ```

  ```mdx title="Recommended approach"
  When a customer provides a confirmation code:

  1. Listen for the spoken format (e.g., "A B C one two three")
  2. Convert to written format (e.g., "ABC123")
  3. Pass to `lookupReservation` tool

  ## Examples

  User says: "My code is A... B... C... one... two... three"
  You format: "ABC123"

  User says: "X Y Z four five six seven eight"
  You format: "XYZ45678"
  ```
</CodeBlocks>

### Dedicate a guardrails section

List all non-negotiable rules the model must always follow in a dedicated `# Guardrails` section. Models are tuned to pay extra attention to this heading.

**Why this matters for reliability:** Guardrails prevent inappropriate responses and ensure compliance with policies. Centralizing them in a dedicated section makes them easier to audit and update.

<CodeBlocks>
  ```mdx title="Recommended approach"
  # Guardrails

  Never share customer data across conversations or reveal sensitive account information without proper verification.
  Never process refunds over $500 without supervisor approval.
  Never make promises about delivery dates that aren't confirmed in the order system.
  Acknowledge when you don't know an answer instead of guessing.
  If a customer becomes abusive, politely end the conversation and offer to escalate to a supervisor.
  ```
</CodeBlocks>

To learn more about designing effective guardrails, see our guide on [safety and moderation](/docs/agents-platform/customization/privacy).

## Tool configuration for reliability

Agents capable of handling transactional workflows can be highly effective. To enable this, they must be equipped with tools that let them perform actions in other systems or fetch live data from them.

Equally important as prompt structure is how you describe the tools available to your agent. Clear, action-oriented tool definitions help the model invoke them correctly and recover gracefully from errors.

### Describe tools precisely with detailed parameters

When creating a tool, add descriptions to all parameters. This helps the LLM construct tool calls accurately.

**Tool description:** "Looks up customer order status by order ID and returns current status, estimated delivery date, and tracking number."

**Parameter descriptions:**

* `order_id` (required): "The unique order identifier, formatted as written characters (e.g., 'ORD123456')"
* `include_history` (optional): "If true, returns full order history including status changes"

**Why this matters for reliability:** Parameter descriptions act as inline documentation for the model. They clarify format expectations, required vs. optional fields, and acceptable values.

### Explain when and how to use each tool in the system prompt

Clearly define in your system prompt when and how each tool should be used. Don't rely solely on tool descriptions—provide usage context and sequencing logic.

<CodeBlocks>
  ```mdx title="Recommended approach"
  # Tools

  You have access to the following tools:

  ## `getOrderStatus`

  Use this tool when a customer asks about their order. Always call this tool before providing order information—never rely on memory or assumptions.

  **When to use:**

  - Customer asks "Where is my order?"
  - Customer provides an order number
  - Customer asks about delivery estimates

  **How to use:**

  1. Collect the order ID from the customer in spoken format
  2. Convert to written format using character normalization rules
  3. Call `getOrderStatus` with the formatted order ID
  4. Present the results to the customer in natural language

  **Error handling:**
  If the tool returns "Order not found", ask the customer to verify the order number and try again.

  ## `processRefund`

  Use this tool only after verifying:

  1. Customer identity has been confirmed
  2. Order is eligible for refund (within 30 days, not already refunded)
  3. Refund amount is under $500 (escalate to supervisor if over $500)

  **Required before calling:**

  - Order ID (from `getOrderStatus`)
  - Refund reason code
  - Customer confirmation

  This step is important: Always confirm refund details with the customer before calling this tool.
  ```
</CodeBlocks>

### Use character normalization for tool inputs

When tools require structured identifiers (emails, phone numbers, codes), ensure the prompt clarifies when to use written vs. spoken formats.

<CodeBlocks>
  ```mdx title="Recommended approach"
  # Tools

  ## `lookupAccount`

  **Parameters:**

  - `email` (required): Customer email address in written format (e.g., "john.smith@company.com")

  **Usage:**

  1. Ask customer for their email in spoken format: "Can you provide your email address?"
  2. Listen for spoken format: "john dot smith at company dot com"
  3. Convert to written format: "john.smith@company.com"
  4. Pass written format to this tool

  **Character normalization for email:**

  - "at" → "@"
  - "dot" → "."
  - Remove spaces between words
  ```
</CodeBlocks>

### Handle tool call failures gracefully

Tools can sometimes fail due to network issues, missing data, or other errors. Include clear instructions in your system prompt for recovery.

**Why this matters for reliability:** Tool failures are inevitable in production. Without explicit handling instructions, agents may hallucinate responses or provide incorrect information.

<CodeBlocks>
  ```mdx title="Recommended approach"
  # Tool error handling

  If any tool call fails or returns an error:

  1. Acknowledge the issue to the customer: "I'm having trouble accessing that information right now."
  2. Do not guess or make up information
  3. Offer alternatives:
     - Try the tool again if it might be a temporary issue
     - Offer to escalate to a human agent
     - Provide a callback option
  4. If the error persists after 2 attempts, escalate to a supervisor

  **Example responses:**

  - "I'm having trouble looking up that order right now. Let me try again... [retry]"
  - "I'm unable to access the order system at the moment. I can transfer you to a specialist who can help, or we can schedule a callback. Which would you prefer?"
  ```
</CodeBlocks>

For detailed guidance on building reliable tool integrations, see our documentation on [Client tools](/docs/agents-platform/customization/tools/client-tools), [Server tools](/docs/agents-platform/customization/tools/server-tools), and [MCP tools](/docs/agents-platform/customization/tools/mcp).

## Architecture patterns for enterprise agents

While strong prompts and tools form the foundation of agent reliability, production systems require thoughtful architectural design. Enterprise agents handle complex workflows that often exceed the scope of a single, monolithic prompt.

### Keep agents specialized

Overly broad instructions or large context windows increase latency and reduce accuracy. Each agent should have a narrow, clearly defined knowledge base and set of responsibilities.

**Why this matters for reliability:** Specialized agents have fewer edge cases to handle, clearer success criteria, and faster response times. They're easier to test, debug, and improve.

<Note>
  A general-purpose "do everything" agent is harder to maintain and more likely to fail in
  production than a network of specialized agents with clear handoffs.
</Note>

### Use orchestrator and specialist patterns

For complex tasks, design multi-agent workflows that hand off tasks between specialized agents—and to human operators when needed.

**Architecture pattern:**

1. **Orchestrator agent:** Routes incoming requests to appropriate specialist agents based on intent classification
2. **Specialist agents:** Handle domain-specific tasks (billing, scheduling, technical support, etc.)
3. **Human escalation:** Defined handoff criteria for complex or sensitive cases

**Benefits of this pattern:**

* Each specialist has a focused prompt and reduced context
* Easier to update individual specialists without affecting the system
* Clear metrics per domain (billing resolution rate, scheduling success rate, etc.)
* Reduced latency per interaction (smaller prompts, faster inference)

### Define clear handoff criteria

When designing multi-agent workflows, specify exactly when and how control should transfer between agents or to human operators.

<CodeBlocks>
  ```mdx title="Orchestrator agent example"
  # Goal

  Route customer requests to the appropriate specialist agent based on intent.

  ## Routing logic

  **Billing specialist:** Customer mentions payment, invoice, refund, charge, subscription, or account balance
  **Technical support specialist:** Customer reports error, bug, issue, not working, broken
  **Scheduling specialist:** Customer wants to book, reschedule, cancel, or check appointment
  **Human escalation:** Customer is angry, requests supervisor, or issue is unresolved after 2 specialist attempts

  ## Handoff process

  1. Classify customer intent based on first message
  2. Provide brief acknowledgment: "I'll connect you with our [billing/technical/scheduling] team."
  3. Transfer conversation with context summary:
     - Customer name
     - Primary issue
     - Any account identifiers already collected
  4. Do not repeat information collection that already occurred
  ```
</CodeBlocks>

<CodeBlocks>
  ```mdx title="Specialist agent example"
  # Personality

  You are a billing specialist for Acme Corp. You handle payment issues, refunds, and subscription changes.

  # Goal

  Resolve billing inquiries by:

  1. Verifying customer identity
  2. Looking up account and billing history
  3. Processing refunds (under $500) or escalating (over $500)
  4. Updating subscription settings when requested

  # Guardrails

  Never access account information without identity verification.
  Never process refunds over $500 without supervisor approval.
  If the customer's issue is not billing-related, transfer back to the orchestrator agent.
  ```
</CodeBlocks>

For detailed guidance on building multi-agent workflows, see our documentation on [Workflows](/docs/agents-platform/customization/agent-workflows).

## Model selection for enterprise reliability

Selecting the right model depends on your performance requirements—particularly latency, accuracy, and tool-calling reliability. Different models offer different tradeoffs between speed, reasoning capability, and cost.

### Understand the tradeoffs

**Latency:** Smaller models (fewer parameters) generally respond faster, making them suitable for high-frequency, low-complexity interactions.

**Accuracy:** Larger models provide stronger reasoning capabilities and better handle complex, multi-step tasks, but with higher latency and cost.

**Tool-calling reliability:** Not all models handle tool/function calling with equal precision. Some excel at structured output, while others may require more explicit prompting.

### Model recommendations by use case

Based on deployments across millions of agent interactions, the following patterns emerge:

* **GPT-4o or GLM 4.5 Air (recommended starting point):** Best for general-purpose enterprise agents where latency, accuracy, and cost must all be balanced. Offers low-to-moderate latency with strong tool-calling performance and reasonable cost per interaction. Ideal for customer support, scheduling, order management, and general inquiry handling.

* **Gemini 2.5 Flash Lite (ultra-low latency):** Best for high-frequency, simple interactions where speed is critical. Provides the lowest latency with broad general knowledge, though with lower performance on complex tool-calling. Cost-effective at scale for initial routing/triage, simple FAQs, appointment confirmations, and basic data collection.

* **Claude Sonnet 4 or 4.5 (complex reasoning):** Best for multi-step problem-solving, nuanced judgment, and complex tool orchestration. Offers the highest accuracy and reasoning capability with excellent tool-calling reliability, though with higher latency and cost. Ideal for tasks where mistakes are costly, such as technical troubleshooting, financial advisory, compliance-sensitive workflows, and complex refund/escalation decisions.

### Benchmark with your actual prompts

Model performance varies significantly based on prompt structure and task complexity. Before committing to a model:

1. Test 2-3 candidate models with your actual system prompt
2. Evaluate on real user queries or synthetic test cases
3. Measure latency, accuracy, and tool-calling success rate
4. Optimize for the best tradeoff given your specific requirements

For detailed model configuration options, see our [Models documentation](/docs/agents-platform/customization/llm).

## Iteration and testing

Reliability in production comes from continuous iteration. Even well-constructed prompts can fail in real use. What matters is learning from those failures and improving through disciplined testing.

### Configure evaluation criteria

Attach concrete evaluation criteria to each agent to monitor success over time and check for regressions.

**Key metrics to track:**

* **Task completion rate:** Percentage of user intents successfully addressed
* **Escalation rate:** Percentage of conversations requiring human intervention

For detailed guidance on configuring evaluation criteria in ElevenLabs, see [Success Evaluation](/docs/agents-platform/customization/agent-analysis/success-evaluation).

### Analyze failure patterns

When agents underperform, identify patterns in problematic interactions:

* **Where does the agent provide incorrect information?** → Strengthen instructions in specific sections
* **When does it fail to understand user intent?** → Add examples or simplify language
* **Which user inputs cause it to break character?** → Add guardrails for edge cases
* **Which tools fail most often?** → Improve error handling or parameter descriptions

Review conversation transcripts where user satisfaction was low or tasks weren't completed.

### Make targeted refinements

Update specific sections of your prompt to address identified issues:

1. **Isolate the problem:** Identify which prompt section or tool definition is causing failures
2. **Test changes on specific examples:** Use conversations that previously failed as test cases
3. **Make one change at a time:** Isolate improvements to understand what works
4. **Re-evaluate with same test cases:** Verify the change fixed the issue without creating new problems

<Warning>
  Avoid making multiple prompt changes simultaneously. This makes it impossible to attribute
  improvements or regressions to specific edits.
</Warning>

### Configure data collection

Configure your agent to summarize data from each conversation. This allows you to analyze interaction patterns, identify common user requests, and continuously improve your prompt based on real-world usage.

For detailed guidance on configuring data collection in ElevenLabs, see [Data Collection](/docs/agents-platform/customization/agent-analysis/data-collection).

### Use simulation for regression testing

Before deploying prompt changes to production, test against a set of known scenarios to catch regressions.

For guidance on testing agents programmatically, see [Simulate Conversations](/docs/agents-platform/guides/simulate-conversations).

## Production considerations

Enterprise agents require additional safeguards beyond prompt quality. Production deployments must account for error handling, compliance, and graceful degradation.

### Handle errors across all tool integrations

Every external tool call is a potential failure point. Ensure your prompt includes explicit error handling for:

* **Network failures:** "I'm having trouble connecting to our system. Let me try again."
* **Missing data:** "I don't see that information in our system. Can you verify the details?"
* **Timeout errors:** "This is taking longer than expected. I can escalate to a specialist or try again."
* **Permission errors:** "I don't have access to that information. Let me transfer you to someone who can help."

## Example prompts

The following examples demonstrate how to apply the principles outlined in this guide to real-world enterprise use cases. Each example includes annotations highlighting which reliability principles are in use.

### Example 1: Technical support agent

<CodeBlocks>
  ```mdx title="Technical support specialist" maxLines=60
  # Personality

  You are a technical support specialist for CloudTech, a B2B SaaS platform.
  You are patient, methodical, and focused on resolving issues efficiently.
  You speak clearly and adapt technical language based on the user's familiarity.

  # Environment

  You are assisting customers via phone support.
  Customers may be experiencing service disruptions and could be frustrated.
  You have access to diagnostic tools and the customer account database.

  # Tone

  Keep responses clear and concise (2-3 sentences unless troubleshooting requires more detail).
  Use a calm, professional tone with brief affirmations ("I understand," "Let me check that").
  Adapt technical depth based on customer responses.
  Check for understanding after complex steps: "Does that make sense?"

  # Goal

  Resolve technical issues through structured troubleshooting:

  1. Verify customer identity using email and account ID
  2. Identify affected service and severity level
  3. Run diagnostics using `runSystemDiagnostic` tool
  4. Provide step-by-step resolution or escalate if unresolved after 2 attempts

  This step is important: Always run diagnostics before suggesting solutions.

  # Guardrails

  Never access customer accounts without identity verification. This step is important.
  Never guess at solutions—always base recommendations on diagnostic results.
  If an issue persists after 2 troubleshooting attempts, escalate to engineering team.
  Acknowledge when you don't know the answer instead of speculating.

  # Tools

  ## `verifyCustomerIdentity`

  **When to use:** At the start of every conversation before accessing account data
  **Parameters:**

  - `email` (required): Customer email in written format (e.g., "user@company.com")
  - `account_id` (optional): Account ID if customer provides it

  **Usage:**

  1. Ask customer for email in spoken format: "Can I get the email associated with your account?"
  2. Convert to written format: "john dot smith at company dot com" → "john.smith@company.com"
  3. Call this tool with written email

  **Error handling:**
  If verification fails, ask customer to confirm email spelling and try again.

  ## `runSystemDiagnostic`

  **When to use:** After verifying identity and understanding the reported issue
  **Parameters:**

  - `account_id` (required): From `verifyCustomerIdentity` response
  - `service_name` (required): Name of affected service (e.g., "api", "dashboard", "storage")

  **Usage:**

  1. Confirm which service is affected
  2. Run diagnostic with account ID and service name
  3. Review results before providing solution

  **Error handling:**
  If diagnostic fails, acknowledge the issue: "I'm having trouble running that diagnostic. Let me escalate to our engineering team."

  # Character normalization

  When collecting email addresses:

  - Spoken: "john dot smith at company dot com"
  - Written: "john.smith@company.com"
  - Convert "@" from "at", "." from "dot", remove spaces

  # Error handling

  If any tool call fails:

  1. Acknowledge: "I'm having trouble accessing that information right now."
  2. Do not guess or make up information
  3. Offer to retry once, then escalate if failure persists
  ```
</CodeBlocks>

**Principles demonstrated:**

* ✓ Clean section separation (`# Personality`, `# Goal`, `# Tools`, etc.)
* ✓ One action per line (see `# Goal` numbered steps)
* ✓ Concise instructions (tone section is brief and clear)
* ✓ Emphasized critical steps ("This step is important")
* ✓ Character normalization (email format conversion)
* ✓ Clear examples (in character normalization section)
* ✓ Dedicated guardrails section
* ✓ Precise tool descriptions with when/how/error guidance
* ✓ Explicit error handling instructions

### Example 2: Customer service refund agent

<CodeBlocks>
  ```mdx title="Refund processing specialist" maxLines=50
  # Personality

  You are a refund specialist for RetailCo.
  You are empathetic, solution-oriented, and efficient.
  You balance customer satisfaction with company policy compliance.

  # Goal

  Process refund requests through this workflow:

  1. Verify customer identity using order number and email
  2. Look up order details with `getOrderDetails` tool
  3. Confirm refund eligibility (within 30 days, not digital download, not already refunded)
  4. For refunds under $100: Process immediately with `processRefund` tool
  5. For refunds $100-$500: Apply secondary verification, then process
  6. For refunds over $500: Escalate to supervisor with case summary

  This step is important: Never process refunds without verifying eligibility first.

  # Guardrails

  Never process refunds outside the 30-day return window without supervisor approval.
  Never process refunds over $500 without supervisor approval. This step is important.
  Never access order information without verifying customer identity.
  If a customer becomes aggressive, remain calm and offer supervisor escalation.

  # Tools

  ## `verifyIdentity`

  **When to use:** At the start of every conversation
  **Parameters:**

  - `order_id` (required): Order ID in written format (e.g., "ORD123456")
  - `email` (required): Customer email in written format

  **Usage:**

  1. Collect order ID: "Can I get your order number?"
     - Spoken: "O R D one two three four five six"
     - Written: "ORD123456"
  2. Collect email and convert to written format
  3. Call this tool with both values

  ## `getOrderDetails`

  **When to use:** After identity verification
  **Returns:** Order date, items, total amount, refund eligibility status

  **Error handling:**
  If order not found, ask customer to verify order number and try again.

  ## `processRefund`

  **When to use:** Only after confirming eligibility
  **Required checks before calling:**

  - Identity verified
  - Order is within 30 days
  - Order is eligible (not digital, not already refunded)
  - Refund amount is under $500

  **Parameters:**

  - `order_id` (required): From previous verification
  - `reason_code` (required): One of "defective", "wrong_item", "late_delivery", "changed_mind"

  **Usage:**

  1. Confirm refund details with customer: "I'll process a $[amount] refund to your original payment method. It will appear in 3-5 business days. Does that work for you?"
  2. Wait for customer confirmation
  3. Call this tool

  **Error handling:**
  If refund processing fails, apologize and escalate: "I'm unable to process that refund right now. Let me escalate to a supervisor who can help."

  # Character normalization

  Order IDs:

  - Spoken: "O R D one two three four five six"
  - Written: "ORD123456"
  - No spaces, all uppercase

  Email addresses:

  - Spoken: "john dot smith at retailco dot com"
  - Written: "john.smith@retailco.com"
  ```
</CodeBlocks>

**Principles demonstrated:**

* ✓ Specialized agent scope (refunds only, not general support)
* ✓ Clear workflow steps in `# Goal` section
* ✓ Repeated emphasis on critical rules (refund limits, verification)
* ✓ Detailed tool usage with "when to use" and "required checks"
* ✓ Character normalization for structured IDs
* ✓ Explicit error handling per tool
* ✓ Escalation criteria clearly defined

## Formatting best practices

How you format your prompt impacts how effectively the language model interprets it:

* **Use markdown headings:** Structure sections with `#` for main sections, `##` for subsections
* **Prefer bulleted lists:** Break down instructions into digestible bullet points
* **Use whitespace:** Separate sections and instruction groups with blank lines
* **Keep headings in sentence case:** `# Goal` not `# GOAL`
* **Be consistent:** Use the same formatting pattern throughout the prompt

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I maintain consistency across multiple agents?">
    Create shared prompt templates for common sections like character normalization, error handling,
    and guardrails. Store these in a central repository and reference them across specialist agents.
    Use the orchestrator pattern to ensure consistent routing logic and handoff procedures.
  </Accordion>

  <Accordion title="What's the minimum viable prompt for production?">
    At minimum, include: (1) Personality/role definition, (2) Primary goal, (3) Core guardrails, and
    (4) Tool descriptions if tools are used. Even simple agents benefit from explicit section
    structure and error handling instructions.
  </Accordion>

  <Accordion title="How do I handle tool deprecation without breaking agents?">
    When deprecating a tool, add a new tool first, then update the prompt to prefer the new tool while
    keeping the old one as a fallback. Monitor usage, then remove the old tool once usage drops to
    zero. Always include error handling so agents can recover if a deprecated tool is called.
  </Accordion>

  <Accordion title="Should I use different prompts for different LLMs?">
    Generally, prompts structured with the principles in this guide work across models. However,
    model-specific tuning can improve performance—particularly for tool-calling format and reasoning
    steps. Test your prompt with multiple models and adjust if needed.
  </Accordion>

  <Accordion title="How long should my system prompt be?">
    No universal limit exists, but prompts over 2000 tokens increase latency and cost. Focus on
    conciseness: every line should serve a clear purpose. If your prompt exceeds 2000 tokens, consider
    splitting into multiple specialized agents or extracting reference material into a knowledge base.
  </Accordion>

  <Accordion title="How do I balance consistency with adaptability?">
    Define core personality traits, goals, and guardrails firmly while allowing flexibility in tone
    and verbosity based on user communication style. Use conditional instructions: "If the user is
    frustrated, acknowledge their concerns before proceeding."
  </Accordion>

  <Accordion title="Can I update prompts after deployment?">
    Yes. System prompts can be modified at any time to adjust behavior. This is particularly useful
    for addressing emerging issues or refining capabilities as you learn from user interactions.
    Always test changes in a staging environment before deploying to production.
  </Accordion>

  <Accordion title="How do I prevent agents from hallucinating when tools fail?">
    Include explicit error handling instructions for every tool. Emphasize "never guess or make up
    information" in the guardrails section. Repeat this instruction in tool-specific error handling
    sections. Test tool failure scenarios during development to ensure agents follow recovery
    instructions.
  </Accordion>
</AccordionGroup>

## Next steps

This guide establishes the foundation for reliable agent behavior through prompt engineering, tool configuration, and architectural patterns. To build production-grade systems, continue with:

* **[Workflows](/docs/agents-platform/customization/agent-workflows):** Design multi-agent orchestration and specialist handoffs
* **[Success Evaluation](/docs/agents-platform/customization/agent-analysis/success-evaluation):** Configure metrics and evaluation criteria
* **[Data Collection](/docs/agents-platform/customization/agent-analysis/data-collection):** Capture structured insights from conversations
* **[Testing](/docs/agents-platform/customization/agent-testing):** Implement regression testing and simulation
* **[Security & Privacy](/docs/agents-platform/customization/privacy):** Ensure compliance and data protection
* **[Our Docs Agent](/docs/agents-platform/guides/elevenlabs-docs-agent):** See a complete case study of these principles in action

For enterprise deployment support, [contact our team](https://elevenlabs.io/contact-sales).


# Models

> Learn how to choose the right model for your use-case

ElevenAgents provides a unified interface to connect your agent to multiple models and providers, offering flexibility, reliability, and cost optimization.

## Key features

* **Unified access**: Switch between providers and models with minimal code changes
* **High reliability**: Automatically cascade from one provider to another if one fails
* **Spend monitoring**: Monitor your spending across different models

## Supported models

Currently, the following models are natively supported and can be configured via the agent settings:

| Provider       | Model                  |
| -------------- | ---------------------- |
| **ElevenLabs** | GLM-4.5-Air            |
|                | Qwen3-30B-A3B          |
|                | GPT-OSS-120B           |
| **Google**     | Gemini 3 Pro Preview   |
|                | Gemini 3 Flash Preview |
|                | Gemini 2.5 Flash       |
|                | Gemini 2.5 Flash Lite  |
|                | Gemini 2.0 Flash       |
|                | Gemini 2.0 Flash Lite  |
| **OpenAI**     | GPT-5                  |
|                | GPT-5 Mini             |
|                | GPT-5 Nano             |
|                | GPT-4.1                |
|                | GPT-4.1 Mini           |
|                | GPT-4.1 Nano           |
|                | GPT-4o                 |
|                | GPT-4o Mini            |
|                | GPT-4 Turbo            |
|                | GPT-3.5 Turbo          |
| **Anthropic**  | Claude Sonnet 4.5      |
|                | Claude Sonnet 4        |
|                | Claude Haiku 4.5       |
|                | Claude 3.7 Sonnet      |
|                | Claude 3.5 Sonnet      |
|                | Claude 3 Haiku         |

<Note>
  Pricing is typically denoted in USD per 1 million tokens unless specified otherwise. A token is a
  fundamental unit of text data for LLMs, roughly equivalent to 4 characters on average.
</Note>

### Custom LLM

Using your own custom LLM is supported by specifying the endpoint we should make requests to and providing credentials through our secure secret storage. Learn more about [custom LLM integration](/docs/agents-platform/customization/llm/custom-llm).

<Note>
  With EU data residency enabled, a small number of older Gemini and Claude LLMs are not available
  in ElevenLabs Agents to maintain compliance with EU data residency. Custom LLMs and OpenAI LLMs
  remain fully available. For more information please see [GDPR and data
  residency](/docs/overview/administration/data-residency).
</Note>

## Choosing a model

Selecting the most suitable LLM for your application involves considering several factors:

* **Task complexity**: More demanding or nuanced tasks generally benefit from more powerful models (e.g., OpenAI's GPT-4 series, Anthropic's Claude Sonnet 4, Google's Gemini 2.5 models)
* **Latency requirements**: For applications requiring real-time or near real-time responses, such as live voice conversations, models optimized for speed are preferable (e.g., Google's Gemini Flash series, Anthropic's Claude Haiku, OpenAI's GPT-4o-mini)
* **Context window size**: If your application needs to process, understand, or recall information from long conversations or extensive documents, select models with larger context windows
* **Cost-effectiveness**: Balance the desired performance and features against your budget. LLM prices can vary significantly, so analyze the pricing structure (input, output, and cache tokens) in relation to your expected usage patterns
* **HIPAA compliance**: If your application involves Protected Health Information (PHI), it is crucial to use an LLM that is designated as HIPAA compliant and ensure your entire data handling process meets regulatory standards

<Note>
  The maximum system prompt size is 2MB, which includes your agent's instructions, knowledge base
  content, and other system-level context.
</Note>

## Model configuration

### Temperature

Temperature controls the randomness of model responses. Lower values produce more consistent, focused outputs while higher values increase creativity and variation.

* **Low (0.0-0.3)**: Deterministic, consistent responses for structured interactions
* **Medium (0.4-0.7)**: Balanced creativity and consistency
* **High (0.8-1.0)**: Creative, varied responses for dynamic conversations

### Backup LLM configuration

Configure backup LLMs to ensure conversation continuity when the primary LLM fails or becomes unavailable.

**Configuration options:**

* **Default**: Uses ElevenLabs' recommended fallback sequence
* **Custom**: Define your own cascading sequence of backup models
* **Disabled**: No fallback (strongly discouraged for production)

<Warning>
  Disabling backup LLMs means conversations will end abruptly if your primary LLM fails or becomes
  unavailable. This is strongly discouraged for production use.
</Warning>

Learn more about [LLM cascading](/docs/agents-platform/customization/llm/llm-cascading).

### Thinking budget

Control how many internal reasoning tokens the model can use before responding. More tokens improve answer quality but slow down response time.

**Options:**

* **Disabled**: Fastest replies with no internal reasoning overhead
* **Low**: Minimal reasoning for quick responses
* **Medium**: Balanced reasoning and speed
* **High**: Maximum reasoning for complex queries

### Reasoning effort

Some models support configurable reasoning effort levels (None, Low, Medium, High).

**For conversational use-cases:**

Keep reasoning effort set to **None** to avoid the agent thinking too long, which can disrupt natural conversation flow.

**For workflow steps:**

Reasoning effort is perfect for workflow steps that require complex thought or decision-making where response time is less critical.

## Understanding pricing

* **Tokens**: LLM usage is typically billed based on the number of tokens processed. As a general guideline for English text, 100 tokens is approximately equivalent to 75 words
* **Input vs. output pricing**: Providers often differentiate pricing for input tokens (the data you send to the model) and output tokens (the data the model generates in response)
* **Cache pricing**:
  * `input_cache_read`: This refers to the cost associated with retrieving previously processed input data from a cache. Utilizing cached data can lead to cost savings if identical inputs are processed multiple times
  * `input_cache_write`: This is the cost associated with storing input data into a cache. Some LLM providers may charge for this operation
* The prices listed in this document are per 1 million tokens and are based on the information available at the time of writing. These prices are subject to change by the LLM providers

For the most accurate and current information on model capabilities, pricing, and terms of service, always consult the official documentation from the respective LLM providers (OpenAI, Google, Anthropic).

## HIPAA compliance

Certain LLMs available on our platform may be suitable for use in environments requiring HIPAA compliance, please see the [HIPAA compliance docs](/docs/agents-platform/legal/hipaa) for more details.

## Related resources

* [Custom LLM integration](/docs/agents-platform/customization/llm/custom-llm)
* [LLM cascading](/docs/agents-platform/customization/llm/llm-cascading)
* [Optimizing costs](/docs/agents-platform/customization/llm/optimizing-costs)


# Workflows

> Build sophisticated conversation flows with visual graph-based workflows

<Frame background="subtle">
  <iframe width="100%" height="400" src="https://www.youtube.com/embed/7gtzXAaA82I" title="Agent Workflows Walkthrough" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />
</Frame>

## Overview

Agent Workflows provide a powerful visual interface for designing complex conversation flows in ElevenAgents. Instead of relying on linear conversation paths, workflows enable you to create sophisticated, branching conversation graphs that adapt dynamically to user needs.

<Frame background="subtle">
  ![Workflow Overview](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0b5b2cf9754c67ef469c08af5d13786f70ca8e0018d10e92595861abb4ed32cb/assets/images/conversational-ai/workflow-overview.png)
</Frame>

## Node types

Workflows are composed of different node types, each serving a specific purpose in your conversation flow.

<Frame background="subtle">
  ![Node Types](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d638a84e1a6dc584a812be436f5da5e665b103b6cb5b6c53840705723bbb5a8f/assets/images/conversational-ai/workflow-node-types.png)
</Frame>

### Subagent nodes

Subagent nodes allow you to modify agent behavior at specific points in your workflow. These modifications are applied on top of the base agent configuration, or can override the current agent's config completely, giving you fine-grained control over each conversation phase.
Any of an agent's configuration, tools available, and attached knowledge base items can be updated/overwitten.

<Tabs>
  <Tab title="General">
    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8ca72df8768a03adc0064281c906ab0f5710153249d17f7e7d51f465da7e9e94/assets/images/conversational-ai/workflow-subagent-extra-agent-config.png" alt="Subagent Extra Agent Config" />
    </Frame>

    Modify core agent settings for this specific node:

    * **System Prompt**: Append or override system instructions to guide agent behavior
    * **LLM Selection**: Choose a different language model (e.g., switch from Gemini 2.0 Flash to a more powerful model for complex reasoning tasks)
    * **Voice Configuration**: Change voice settings including speed, tone, or even switch to a different voice

    **Use Cases:**

    * Use a more powerful LLM for complex decision-making nodes
    * Apply stricter conversation guidelines during sensitive information gathering
    * Change voice characteristics for different conversation phases
    * Modify agent personality for specific interaction types
  </Tab>

  <Tab title="Knowledge Base">
    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/168a56fc316596983275999c53bbbe391c4c30a05abedc17cb6a4566eff7773f/assets/images/conversational-ai/workflow-subagent-node-extra-kb.png" alt="Subagent Extra Knowledge Base" />
    </Frame>

    Add node-specific knowledge without affecting the global knowledge base:

    * **Include Global Knowledge Base**: Toggle whether to include the agent's main knowledge base
    * **Additional Documents**: Add documents specific to this conversation phase
    * **Dynamic Knowledge**: Inject contextual information based on workflow state

    **Use Cases:**

    * Add product-specific documentation during sales conversations
    * Include compliance guidelines during authentication
    * Provide troubleshooting guides for support flows
    * Add pricing information only after qualification
  </Tab>

  <Tab title="Tools">
    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9af53c3227661fd88bec57cb21197eb289760d33a874b56152d507373e51bac1/assets/images/conversational-ai/workflow-sub-agent-config-extra-tools.png" alt="Subagent Extra Tools" />
    </Frame>

    Manage which tools are available to the agent at this node:

    * **Include Global Tools**: Toggle whether to include tools from the main agent configuration
    * **Additional Tools**: Add tools specific to this workflow node (e.g., webhook tools like `book_meeting`)
    * **Tool Type**: Specify whether tools are webhooks, API calls, or other integrations

    **Use Cases:**

    * Add authentication tools only after initial qualification
    * Enable payment processing tools at checkout nodes
    * Provide CRM access after user verification
    * Add scheduling tools for appointment booking phases
    * Include webhook tools for specific actions like booking meetings
  </Tab>
</Tabs>

### Dispatch tool node

Tool nodes execute a specific tool call during conversation flow. Unlike tools within subagents, tool nodes are dedicated execution points that guarantee the tool is called.

<Frame background="subtle">
  ![Tool Node Result Edges](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b60603e56dfb25e89cdfe4223826f635af874e034af8936d74d3b428611e17b/assets/images/conversational-ai/workflow-tool-node-result-edges.png)
</Frame>

**Special Edge Configuration:**
Tool nodes have a unique edge type that allows routing to a new node based on the tool execution result. You can define:

* **Success path**: Where to route when the tool executes successfully
* **Failure path**: Where to route when the tool fails or returns an error

In future, futher branching conditions will be provided.

### Agent transfer node

Agent transfer node facilitate handoffs the conversation between different conversational agents, learn more [here](/docs/agents-platform/customization/tools/system-tools/agent-transfer).

### Transfer to number node

Transfer to number nodes transitions from a conversation with an AI agent to a human agent via phone systems, learn more [here](/docs/agents-platform/customization/tools/system-tools/transfer-to-human)

### End node

End call nodes terminate the conversation flow gracefully, learn more [here](/docs/agents-platform/customization/tools/system-tools/transfer-to-human#:~:text=System%20tools-,End%20call,-Language%20detection)

## Edges and flow control

Edges define how conversations flow between nodes in your workflow. They support sophisticated routing logic that enables dynamic, context-aware conversation paths.

<Frame background="subtle">
  ![Workflow Edges](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/02d664c9211bb8cf5452b80ab865f26b8d0b723a6acff75141ea1e9c43f7dbab/assets/images/conversational-ai/workflow-edges.png)
</Frame>

<Tabs>
  <Tab title="Forward Edges">
    Forward edges move the conversation to subsequent nodes in the workflow. They represent the primary flow of your conversation.

    <Frame background="subtle">
      ![Forward Edge Configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2400c66bf6f60b0d4262ecd828dea93847197f7cc00d9c8964e6486419bc90be/assets/images/conversational-ai/workflow-edge-forward.png)
    </Frame>
  </Tab>

  <Tab title="Backward Edges">
    Backward edges allow conversations to loop back to previous nodes, enabling iterative interactions and retry logic.

    <Frame background="subtle">
      ![Backward Edge Configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e211da75e56c826fd763ae4d8149604a866d3ec63271c572e177d52bb9a80e14/assets/images/conversational-ai/workflow-edge-backward.png)
    </Frame>

    **Use Cases:**

    * Retry failed authentication attempts
    * Loop back for additional information gathering
    * Re-qualification after changes in user requirements
    * Iterative troubleshooting processes
  </Tab>
</Tabs>

<Tabs>
  <Tab title="LLM Condition">
    Use LLM conditions to create dynamic conversation flows based on natural language evaluation. The LLM evaluates conditions in real-time to determine the appropriate path.

    <Frame background="subtle">
      ![LLM Condition Agent Transfer](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/507885879d781f291ab35b7dda84e760767a5544ffb6bf7b455e7a1cc19b78b7/assets/images/conversational-ai/workflow-agent-transfer-llm-condition.png)
    </Frame>

    **Configuration Options:**

    * **Label**: Human-readable description of the edge condition (not processed by LLM)
    * **LLM Condition**: Natural language condition evaluated by the LLM
  </Tab>

  <Tab title="Expression">
    Use expressions to create conditional logic based on variables and structured data.

    <Frame background="subtle">
      ![Expression Agent Transfer](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/712fc40d707906a7c6ccb4b0a76f0fd3857278176606d441bfb5245f5f6e0ffe/assets/images/conversational-ai/workflow-agent-transfer-expression.png)
    </Frame>

    **Configuration Options:**

    * **Label**: Human-readable description of the edge condition (not processed by LLM)
    * **Expression**: Deterministic evaluation criteria based on data structure
  </Tab>

  <Tab title="None">
    Unconditional transitions automatically move the conversation to the next node without any conditions.

    <Frame background="subtle">
      ![Unconditional Agent Transfer](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/73b70ce7c783277e64ba533f6d69c84e2ed3120f1fd03dbdebcd4d4f5358eb5b/assets/images/conversational-ai/workflow-agent-transfer-none.png)
    </Frame>

    **Use Cases:**

    * Sequential steps that always follow one another
    * Automatic progression after completing an action
    * Default fallback paths
  </Tab>
</Tabs>


# Conversation flow

> Configure how your assistant handles timeouts, interruptions, and turn-taking during conversations.

## Overview

Conversation flow settings determine how your assistant handles periods of user silence, interruptions during speech, and turn-taking behavior. These settings help create more natural conversations and can be customized based on your use case.

<CardGroup cols={3}>
  <Card title="Timeouts" icon="clock" href="#timeouts">
    Configure how long your assistant waits during periods of silence
  </Card>

  <Card title="Interruptions" icon="hand" href="#interruptions">
    Control whether users can interrupt your assistant while speaking
  </Card>

  <Card title="Turn eagerness" icon="arrows-turn-to-dots" href="#turn-eagerness">
    Adjust how quickly your assistant responds to user input
  </Card>
</CardGroup>

## Timeouts

Timeout handling determines how long your assistant will wait during periods of user silence before prompting for a response.

### Configuration

Timeout settings can be configured in the agent's **Advanced** tab under **Turn Timeout**.

The timeout duration is specified in seconds and determines how long the assistant will wait in silence before prompting the user. Turn timeouts must be between 1 and 30 seconds.

#### Example timeout settings

<Frame background="subtle">
  ![Timeout settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b0b1941575dd4ff3c7b68f1370bd5419c0a0a1d26aa106b35264afb0a3df1329/assets/images/conversational-ai/timeouts.png)
</Frame>

<Note>
  Choose an appropriate timeout duration based on your use case. Shorter timeouts create more
  responsive conversations but may interrupt users who need more time to respond, leading to a less
  natural conversation.
</Note>

### Best practices for timeouts

* Set shorter timeouts (5-10 seconds) for casual conversations where quick back-and-forth is expected
* Use longer timeouts (10-30 seconds) when users may need more time to think or formulate complex responses
* Consider your user context - customer service may benefit from shorter timeouts while technical support may need longer ones

## Interruptions

Interruption handling determines whether users can interrupt your assistant while it's speaking.

### Configuration

Interruption settings can be configured in the agent's **Advanced** tab under **Client Events**.

To enable interruptions, make sure interruption is a selected client event.

#### Interruptions enabled

<Frame background="subtle">
  ![Interruption allowed](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1da794be8ea3bfed45d06241ce5db390480cd45d27c0f886943518bd52d76157/assets/images/conversational-ai/interruptions.png)
</Frame>

#### Interruptions disabled

<Frame background="subtle">
  ![Interruption ignored](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/847a2ebcdfff9498501502ab4b568fc498b6995f860a5552177a7883942197ff/assets/images/conversational-ai/no-interruption.png)
</Frame>

<Note>
  Disable interruptions when the complete delivery of information is crucial, such as legal
  disclaimers or safety instructions.
</Note>

### Best practices for interruptions

* Enable interruptions for natural conversational flows where back-and-forth dialogue is expected
* Disable interruptions when message completion is critical (e.g., terms and conditions, safety information)
* Consider your use case context - customer service may benefit from interruptions while information delivery may not

## Turn eagerness

Turn eagerness controls how quickly your assistant responds to user input during conversation. This setting determines how eager the assistant is to take turns and start speaking based on detected speech patterns.

### How it works

The assistant now includes two key improvements for more natural turn-taking:

1. **Faster response generation** - The assistant starts speaking after receiving enough words and a comma from the language model, rather than waiting for complete sentences. This reduces latency and creates more responsive conversations, especially when the assistant has longer responses.

2. **Configurable turn eagerness** - Control how quickly the assistant interprets pauses or speech patterns as opportunities to respond.

### Configuration

Turn eagerness can be configured in the dashboard Agent settings or via the [API](/docs/api-reference/agents/create#request.body.conversation_config.turn.turn_eagerness). Three modes are available:

* **Eager** - The assistant responds quickly to user input, jumping in at the earliest opportunity. Best for fast-paced conversations where immediate responses are valued.
* **Normal** - Balanced turn-taking that works well for most conversational scenarios. The assistant waits for natural conversation breaks before responding.
* **Patient** - The assistant waits longer before taking its turn, giving users more time to complete their thoughts. Ideal for collecting detailed information or when users need time to formulate responses.

<Note>
  Turn eagerness is especially powerful when combined with workflows. You can dynamically adjust the
  assistant's responsiveness based on context—making it jump in faster during casual conversation,
  or wait longer when collecting sensitive information like phone numbers or email addresses.
</Note>

### Best practices for turn eagerness

* Use **Eager** mode for customer service scenarios where quick responses improve user experience
* Use **Patient** mode when collecting structured information like phone numbers, addresses, or email addresses
* Use **Normal** mode as a default for general conversational flows
* Combine with workflows to dynamically adjust turn eagerness based on conversation context
* Test different settings with your specific use case to find the optimal balance

## Recommended configurations

<AccordionGroup>
  <Accordion title="Customer service">
    * Shorter timeouts (5-10 seconds) for responsive interactions - Enable interruptions to allow
      customers to interject with questions - **Eager** turn eagerness for quick, responsive
      conversations
  </Accordion>

  <Accordion title="Information collection">
    * Moderate timeouts (10-15 seconds) to allow users time to gather information - Enable
      interruptions for natural conversation flow - **Patient** turn eagerness when collecting phone
      numbers, addresses, or email addresses
  </Accordion>

  <Accordion title="Legal disclaimers">
    * Longer timeouts (15-30 seconds) to allow for complex responses - Disable interruptions to
      ensure full delivery of legal information - **Normal** turn eagerness to maintain steady pacing
  </Accordion>

  <Accordion title="Conversational EdTech">
    * Longer timeouts (10-30 seconds) to allow time to think and formulate responses - Enable
      interruptions to allow students to interject with questions - **Patient** turn eagerness to give
      students adequate time to respond
  </Accordion>
</AccordionGroup>


# Voice customization

> Learn how to customize your AI agent's voice and speech patterns.

## Overview

You can customize various aspects of your AI agent's voice to create a more natural and engaging conversation experience. This includes controlling pronunciation, speaking speed, and language-specific voice settings.

## Available customizations

<CardGroup cols={3}>
  <Card title="Multi-voice support" icon="microphone-lines" href="/docs/agents-platform/customization/voice/multi-voice-support">
    Enable your agent to switch between different voices for multi-character conversations,
    storytelling, and language tutoring.
  </Card>

  <Card title="Pronunciation dictionary" icon="microphone-stand" href="/docs/agents-platform/customization/voice/pronunciation-dictionary">
    Control how your agent pronounces specific words and phrases using
    [IPA](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) or
    [CMU](https://en.wikipedia.org/wiki/CMU_Pronouncing_Dictionary) notation.
  </Card>

  <Card title="Speed control" icon="waveform" href="/docs/agents-platform/customization/voice/speed-control">
    Adjust how quickly or slowly your agent speaks, with values ranging from 0.7x to 1.2x.
  </Card>

  <Card title="Expressive mode" icon="face-laugh" href="/docs/agents-platform/customization/voice/expressive-mode">
    Enable expressive tags like \[laughs], \[whispers], and \[slow] for enhanced emotional delivery.
  </Card>

  <Card title="Language-specific voices" icon="language" href="/docs/agents-platform/customization/voice/customization/language">
    Configure different voices for each supported language to ensure natural pronunciation.
  </Card>
</CardGroup>

## Best practices

<AccordionGroup>
  <Accordion title="Voice selection">
    Choose voices that match your target language and region for the most natural pronunciation.
    Consider testing multiple voices to find the best fit for your use case.
  </Accordion>

  <Accordion title="Speed optimization">
    Start with the default speed (1.0) and adjust based on your specific needs. Test different
    speeds with your content to find the optimal balance between clarity and natural flow.
  </Accordion>

  <Accordion title="Pronunciation dictionaries">
    Focus on terms specific to your business or use case that need consistent pronunciation and are
    not widely used in everyday conversation. Test pronunciations with your chosen voice and model
    combination.
  </Accordion>
</AccordionGroup>

<Note>
  Some voice customization features may be model-dependent. For example, phoneme-based pronunciation
  control is only available with the Turbo v2 model.
</Note>


# Multi-voice support

> Enable your AI agent to switch between different voices for multi-character conversations and enhanced storytelling.

## Overview

Multi-voice support allows your ElevenLabs agent to dynamically switch between different ElevenLabs voices during a single conversation. This powerful feature enables:

* **Multi-character storytelling**: Different voices for different characters in narratives
* **Language tutoring**: Native speaker voices for different languages
* **Emotional agents**: Voice changes based on emotional context
* **Role-playing scenarios**: Distinct voices for different personas

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a421eaed65575340ef34c1209a30d97ca2594a5fb48ee57b02c8349930191727/assets/images/conversational-ai/supported-voices.png" alt="Multi-voice configuration interface" />
</Frame>

## How it works

When multi-voice support is enabled, your agent can use XML-style markup to switch between configured voices during text generation. The agent automatically returns to the default voice when no specific voice is specified.

<CodeBlocks>
  ```xml title="Example voice switching"
  The teacher said, <spanish>¡Hola estudiantes!</spanish> 
  Then the student replied, <student>Hello! How are you today?</student>
  ```

  ```xml title="Multi-character dialogue"
  <narrator>Once upon a time, in a distant kingdom...</narrator>
  <princess>I need to find the magic crystal!</princess>
  <wizard>The crystal lies beyond the enchanted forest.</wizard>
  ```
</CodeBlocks>

## Configuration

### Adding supported voices

Navigate to your agent settings and locate the **Multi-voice support** section under the `Voice` tab.

<Steps>
  ### Add a new voice

  Click **Add voice** to configure a new supported voice for your agent.

  <Frame background="subtle">
    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e7a6e86ed58abb54f75e884214e6bc056c85e85fc60176924fb2683e16250aa1/assets/images/conversational-ai/add-supported-voice.png" alt="Multi-voice configuration interface" />
  </Frame>

  ### Configure voice properties

  Set up the voice with the following details:

  * **Voice label**: Unique identifier (e.g., "Joe", "Spanish", "Happy")
  * **Voice**: Select from your available ElevenLabs voices
  * **Model Family**: Choose Turbo, Flash, or Multilingual (optional)
  * **Language**: Override the default language for this voice (optional)
  * **Description**: When the agent should use this voice

  ### Save configuration

  Click **Add voice** to save the configuration. The voice will be available for your agent to use immediately.
</Steps>

### Voice properties

<AccordionGroup>
  <Accordion title="Voice label">
    A unique identifier that the LLM uses to reference this voice. Choose descriptive labels like: -
    Character names: "Alice", "Bob", "Narrator" - Languages: "Spanish", "French", "German" -
    Emotions: "Happy", "Sad", "Excited" - Roles: "Teacher", "Student", "Guide"
  </Accordion>

  <Accordion title="Model family">
    Override the agent's default model family for this specific voice: - **Flash**: Fastest eneration,
    optimized for real-time use - **Turbo**: Balanced speed and quality - **Multilingual**: Highest
    quality, best for non-English languages - **Same as agent**: Use agent's default setting
  </Accordion>

  <Accordion title="Language override">
    Specify a different language for this voice, useful for: - Multilingual conversations - Language
    tutoring applications - Region-specific pronunciations
  </Accordion>

  <Accordion title="Description">
    Provide context for when the agent should use this voice.
    Examples:

    * "For any Spanish words or phrases"
    * "When the message content is joyful or excited"
    * "Whenever the character Joe is speaking"
  </Accordion>
</AccordionGroup>

## Implementation

### XML markup syntax

Your agent uses XML-style tags to switch between voices:

```xml
<VOICE_LABEL>text to be spoken</VOICE_LABEL>
```

**Key points:**

* Replace `VOICE_LABEL` with the exact label you configured
* Text outside tags uses the default voice
* Tags are case-sensitive
* Nested tags are not supported

### System prompt integration

When you configure supported voices, the system automatically adds instructions to your agent's prompt:

```
When a message should be spoken by a particular person, use markup: "<CHARACTER>message</CHARACTER>" where CHARACTER is the character label.

Available voices are as follows:
- default: any text outside of the CHARACTER tags
- Joe: Whenever Joe is speaking
- Spanish: For any Spanish words or phrases
- Narrator: For narrative descriptions
```

### Example usage

<Tabs>
  <Tab title="Language tutoring">
    ```
    Teacher: Let's practice greetings. In Spanish, we say <Spanish>¡Hola! ¿Cómo estás?</Spanish>
    Student: How do I respond?
    Teacher: You can say <Spanish>¡Hola! Estoy bien, gracias.</Spanish> which means Hello! I'm fine, thank you.
    ```
  </Tab>

  <Tab title="Storytelling">
    ```
    Once upon a time, a brave princess ventured into a dark cave.
    <Princess>I'm not afraid of you, dragon!</Princess> she declared boldly. The dragon rumbled from
    the shadows, <Dragon>You should be, little one.</Dragon>
    But the princess stood her ground, ready for whatever came next.
    ```
  </Tab>
</Tabs>

## Best practices

<AccordionGroup>
  <Accordion title="Voice selection">
    * Choose voices that clearly differentiate between characters or contexts
    * Test voice combinations to ensure they work well together
    * Consider the emotional tone and personality for each voice
    * Ensure voices match the language and accent when switching languages
  </Accordion>

  <Accordion title="Label naming">
    * Use descriptive, intuitive labels that the LLM can understand
    * Keep labels short and memorable
    * Avoid special characters or spaces in labels
  </Accordion>

  <Accordion title="Performance optimization">
    * Limit the number of supported voices to what you actually need
    * Use the same model family when possible to reduce switching overhead
    * Test with your expected conversation patterns
    * Monitor response times with multiple voice switches
  </Accordion>

  <Accordion title="Content guidelines">
    * Provide clear descriptions for when each voice should be used
    * Test edge cases where voice switching might be unclear
    * Consider fallback behavior when voice labels are ambiguous
    * Ensure voice switches enhance rather than distract from the conversation
  </Accordion>
</AccordionGroup>

## Limitations

<Note>
  * Maximum of 10 supported voices per agent (including default)
  * Voice switching adds minimal latency during generation
  * XML tags must be properly formatted and closed
  * Voice labels are case-sensitive in markup
  * Nested voice tags are not supported
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="What happens if I use an undefined voice label?">
    If the agent uses a voice label that hasn't been configured, the text will be spoken using the
    default voice. The XML tags will be ignored.
  </Accordion>

  <Accordion title="Can I change voices mid-sentence?">
    Yes, you can switch voices within a single response. Each tagged section will use the specified
    voice, while untagged text uses the default voice.
  </Accordion>

  <Accordion title="Do voice switches affect conversation latency?">
    Voice switching adds minimal overhead. The first use of each voice in a conversation may have
    slightly higher latency as the voice is initialized.
  </Accordion>

  <Accordion title="Can I use the same voice with different labels?">
    Yes, you can configure multiple labels that use the same ElevenLabs voice but with different model
    families, languages, or contexts.
  </Accordion>

  <Accordion title="How do I train my agent to use voice switching effectively?">
    Provide clear examples in your system prompt and test thoroughly. You can include specific
    scenarios where voice switching should occur and examples of the XML markup format.
  </Accordion>
</AccordionGroup>


# Pronunciation dictionaries

> Learn how to control how your AI agent pronounces specific words and phrases.

## Overview

Pronunciation dictionaries allow you to customize how your AI agent pronounces specific words or phrases. This is particularly useful for:

* Correcting pronunciation of names, places, or technical terms
* Ensuring consistent pronunciation across conversations
* Customizing regional pronunciation variations

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/79d07bdeff752e43943a4c2fa3a04fc7c7dc79bc247fc9a633654d4df4cd895e/assets/images/conversational-ai/pd-convai.png" alt="Pronunciation dictionary settings under the Voice tab" />
</Frame>

## Configuration

You can find the pronunciation dictionary settings under the **Voice** tab in your agent's configuration.

<Note>
  Phoneme tags only work with the `eleven_flash_v2` and `eleven_turbo_v2` models. When used with
  other models, the tags are silently skipped and the default pronunciation is used.

  Phoneme tags (IPA or CMU) only work for English. For other languages, use alias tags instead to
  substitute spellings or phrases that produce the pronunciation you need.
</Note>

## Dictionary file format

Pronunciation dictionaries use XML-based `.pls` files. Here's an example structure:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0"
      xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.w3.org/2005/01/pronunciation-lexicon
        http://www.w3.org/TR/2007/CR-pronunciation-lexicon-20071212/pls.xsd"
      alphabet="ipa" xml:lang="en-GB">
  <lexeme>
    <grapheme>Apple</grapheme>
    <phoneme>ˈæpl̩</phoneme>
  </lexeme>
  <lexeme>
    <grapheme>UN</grapheme>
    <alias>United Nations</alias>
  </lexeme>
</lexicon>
```

## Supported formats

We support two types of pronunciation notation:

1. **IPA (International Phonetic Alphabet)**

   * More precise control over pronunciation
   * Requires knowledge of IPA symbols
   * Example: "nginx" as `/ˈɛndʒɪnˈɛks/`

2. **CMU (Carnegie Mellon University) Dictionary format**
   * Simpler ASCII-based format
   * More accessible for English pronunciations
   * Example: "tomato" as "T AH M EY T OW"

<Tip>
  You can use AI tools like Claude or ChatGPT to help generate IPA or CMU notations for specific
  words.
</Tip>

## Best practices

1. **Case sensitivity**: Create separate entries for capitalized and lowercase versions of words if needed
2. **Testing**: Always test pronunciations with your chosen voice and model
3. **Maintenance**: Keep your dictionary organized and documented
4. **Scope**: Focus on words that are frequently mispronounced or critical to your use case

## FAQ

<AccordionGroup>
  <Accordion title="Which models support phoneme-based pronunciation?">
    Phoneme tags are supported on `eleven_flash_v2` and `eleven_turbo_v2`. All other models skip the
    phoneme entry and fall back to their normal pronunciation. For non-English languages, rely on
    alias tags because phoneme tags only cover English pronunciations.
  </Accordion>

  <Accordion title="Can I use multiple dictionaries?">
    Yes, you can upload multiple dictionary files to handle different sets of pronunciations.
  </Accordion>

  <Accordion title="What happens if a word isn't in the dictionary?">
    The model will use its default pronunciation rules for any words not specified in the
    dictionary.
  </Accordion>
</AccordionGroup>

## Additional resources

* [Professional Voice Cloning](/docs/creative-platform/voices/voice-cloning/professional-voice-cloning)
* [Voice Design](/docs/creative-platform/voices/voice-design)
* [Text to Speech API Reference](/docs/api-reference/text-to-speech/convert)


# Speed control

> Learn how to adjust the speaking speed of your ElevenLabs agent.

## Overview

The speed control feature allows you to adjust how quickly or slowly your agent speaks. This can be useful for:

* Making speech more accessible for different audiences
* Matching specific use cases (e.g., slower for educational content)
* Optimizing for different types of conversations

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4a1dfe1db33f9f03bb614b56173c7c00596f2d6c36b0f17ce43f151bd4d07f66/assets/images/conversational-ai/speed-control.png" alt="Speed control settings under the Voice tab" />
</Frame>

## Configuration

Speed is controlled through the [`speed` parameter](/docs/api-reference/agents/create#request.body.conversation_config.tts.speed) with the following specifications:

* **Range**: 0.7 to 1.2
* **Default**: 1.0
* **Type**: Optional

## How it works

The speed parameter affects the pace of speech generation:

* Values below 1.0 slow down the speech
* Values above 1.0 speed up the speech
* 1.0 represents normal speaking speed

<Note>
  Extreme values near the minimum or maximum may affect the quality of the generated speech.
</Note>

## Best practices

* Start with the default speed (1.0) and adjust based on user feedback
* Test different speeds with your specific content
* Consider your target audience when setting the speed
* Monitor speech quality at extreme values

<Warning>
  Values outside the 0.7-1.2 range are not supported.
</Warning>


# Expressive mode

> Enable your AI agent to use expressive tags for enhanced emotional delivery and speech control.

<Warning>
  Expressive mode is currently in private beta and available only to select workspaces. Contact your
  account manager for access.
</Warning>

## Overview

Expressive mode is a specialized Text to Speech model designed specifically for expressive conversational agents. It enables your ElevenLabs agent to generate expressive tags that control how text is spoken, adding nuanced emotional delivery and speech patterns to your agent's responses. When enabled, the LLM can output special tags in its responses that the expressive TTS model interprets to modify the audio synthesis.

Key capabilities:

* **Emotional expression**: Add laughter, crying, or other emotional cues
* **Speech style control**: Whisper, slow down, or modify delivery
* **Dynamic emphasis**: Apply expressive tags contextually during conversation
* **Natural interactions**: Create more human-like and engaging conversations

## How it works

When expressive mode is enabled, your agent can output special tags in its responses that control the audio synthesis. These tags apply to approximately 4-5 words following the tag, creating natural expressive speech.

<Note>
  Expressive tags typically affect the next 4-5 words of generated speech before returning to normal
  delivery. The exact duration may vary based on the content and context.
</Note>

## Configuration

### Enabling expressive mode

<Steps>
  ### Access your agent settings

  Navigate to your agent configuration in the ElevenLabs dashboard.

  ### Enable the Eleven Expressive model

  Locate the Text to Speech model family option under the `Agent Voice` tab and enable `V3 Conversational` for your agent.

  <Frame background="subtle">
    ![Enabling expressive mode](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/dc666e7c58cef93ee57b9ebcb29a734736d38e6065ce78a78a6a87fe2c6fcb95/assets/images/conversational-ai/expressivemode.gif)
  </Frame>

  ### Update system prompt

  Add instructions to your agent's system prompt to explain the expressive tag functionality.
</Steps>

### System prompt configuration

To use expressive mode effectively, you must instruct your LLM about this capability in your system prompt. Here's a recommended template:

```text
You are a conversational AI agent that can generate expressive speech. You have access to
expressive tags that control how your responses are spoken.

You can use expressive tags in your responses to add emotional nuance and speech style
control. Common effective tags include simple one-word adjectives or verbs like:
- [laughs] - Adds laughter to the speech
- [cries] - Adds crying or emotional tone
- [whispers] - Lowers volume for whispering
- [slow] - Slows down speech delivery
- [excited] - Adds excitement to the delivery
- [sighs] - Adds a sighing quality

Feel free to experiment with other single-word expressive tags that match the emotional
context of your response. Each tag affects approximately the next 4-5 words.

Example: "That's amazing! [laughs] I can't believe it worked on the first try."
```

<Tip>
  Encourage your LLM to use specific tags by providing examples in your system prompt. This helps
  the model understand when and how to apply expressive elements effectively.
</Tip>

## Implementation examples

### Basic usage

<CodeBlocks>
  ```text title="Joyful response"
  User: I just got accepted to my dream university!
  Agent: That's incredible news! [laughs] I'm so happy for you! This is just the beginning of an amazing journey.
  ```

  ```text title="Empathetic response"
  User: I'm really struggling with this situation.
  Agent: I understand how difficult this must be. [slow] Take your time, and remember that it's okay to feel this way.
  ```

  ```text title="Patient repsonses"
  User: Can you tell me the answer to my technical issue?
  Agent: [slow] The issue is that your mac requires an upgrade, [patient] to at least version 2.1.2.
  ```
</CodeBlocks>

### Advanced patterns

<Tabs>
  <Tab title="Storytelling">
    ```text
    Once upon a time, there was a young adventurer who discovered a hidden cave.
    [whispers] Inside, they found something extraordinary. [slow] A glowing crystal that pulsed
    with ancient magic. [laughs] They couldn't believe their luck!
    ```
  </Tab>

  <Tab title="Customer support">
    ```text
    I completely understand your frustration with the delayed shipment. [slow] Let me check
    what's happening with your order right away. [laughs] Actually, I have some good news -
    it's out for delivery today!
    ```
  </Tab>
</Tabs>

## Best practices

<AccordionGroup>
  <Accordion title="Context-appropriate usage">
    Ensure the expressive tags match the emotional context of the conversation. Using \[laughs] during a serious discussion can feel inappropriate and undermine user trust.
  </Accordion>

  <Accordion title="Test thoroughly">
    Different voices may render expressive tags differently. Test your agent with various voices to ensure the expressive elements work as intended.
  </Accordion>

  <Accordion title="System prompt clarity">
    Provide clear, detailed instructions in your system prompt about when and how to use expressive tags. Include specific examples to guide the LLM's behavior.
  </Accordion>

  <Accordion title="Consider cultural context">
    Expressive elements like laughter or crying may be interpreted differently across cultures. Consider your target audience when implementing expressive mode.
  </Accordion>

  <Accordion title="Monitor performance">
    Track how users respond to expressive elements. Collect feedback to refine when and how your agent uses these tags.
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  * Expressive mode is currently in alpha
  * Tag effects last approximately 4-5 words
  * Not all voices may support all expressive tags equally
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="How long does each tag effect last?">
    Each expressive tag typically affects the next 4-5 words of speech. The exact duration may vary slightly based on word length and context, but the system is designed to return to normal delivery naturally.
  </Accordion>

  <Accordion title="What happens if I use tags with voices that don't support them?">
    The system will do its best to render the expressive element, but results may vary depending on the voice's capabilities. Some voices may be more expressive than others.
  </Accordion>

  <Accordion title="How do I know if my workspace has access?">
    Expressive mode is currently available only to select workspaces in private beta. If you don't see the option in your agent settings, contact your ElevenLabs account manager to inquire about access.
  </Accordion>

  <Accordion title="What expressive tags can I use?">
    You can prompt the LLM to use any expressive tag, but certain tags are more likely to work effectively. Common one-word adjectives and verbs (like \[laughs], \[cries], \[whispers], \[slow], \[excited], \[sighs]) tend to produce the most reliable results. The expressive TTS model interprets these tags contextually.
  </Accordion>

  <Accordion title="Does using expressive mode affect pricing?">
    Expressive mode uses the same pricing structure as standard agent conversations. There are no additional charges for using expressive tags.
  </Accordion>

  <Accordion title="How can I train my LLM to use expressive tags effectively?">
    Include clear examples and guidelines in your system prompt. Provide specific scenarios where each tag should be used, and test thoroughly. Consider using few-shot examples to demonstrate appropriate usage patterns.
  </Accordion>
</AccordionGroup>

## Related features

<CardGroup cols={2}>
  <Card title="Multi-voice support" icon="microphone-lines" href="/docs/agents-platform/customization/voice/multi-voice-support">
    Switch between different voices for enhanced character representation
  </Card>

  <Card title="Speed control" icon="waveform" href="/docs/agents-platform/customization/voice/speed-control">
    Adjust the overall speaking speed of your agent
  </Card>

  <Card title="Voice design" icon="palette" href="/docs/agents-platform/customization/voice/best-practices/conversational-voice-design">
    Learn best practices for creating engaging conversational voices
  </Card>

  <Card title="System prompt guide" icon="message-lines" href="/docs/agents-platform/best-practices/prompting-guide">
    Optimize your agent's behavior with effective prompting
  </Card>
</CardGroup>


# Conversational voice design

> Learn how to design lifelike, engaging voices for ElevenLabs Agents

## Overview

Selecting the right voice is crucial for creating an effective voice agent. The voice you choose should align with your agent's personality, tone, and purpose.

## Voice design

If you need a voice that doesn't exist in our library, [Voice Design](/docs/creative-platform/voices/voice-design) lets you create custom voices from text descriptions. Define characteristics like age, accent, tone, and pacing to generate voices tailored to your agent's personality and use case.

## Library voices

These voices offer a range of styles and characteristics that work well for different agent types:

* `kdmDKE6EkgrWrrykO9Qt` - **Alexandra:** A super realistic, young female voice that likes to chat
* `L0Dsvb3SLTyegXwtm47J` - **Archer:** Grounded and friendly young British male with charm
* `g6xIsTj2HwM6VR4iXFCw` - **Jessica Anne Bogart:** Empathetic and expressive, great for wellness coaches
* `OYTbf65OHHFELVut7v2H` - **Hope:** Bright and uplifting, perfect for positive interactions
* `dj3G1R1ilKoFKhBnWOzG` - **Eryn:** Friendly and relatable, ideal for casual interactions
* `HDA9tsk27wYi3uq0fPcK` - **Stuart:** Professional & friendly Aussie, ideal for technical assistance
* `1SM7GgM6IMuvQlz2BwM3` - **Mark:** Relaxed and laid back, suitable for non chalant chats
* `PT4nqlKZfc06VW1BuClj` - **Angela:** Raw and relatable, great listener and down to earth
* `vBKc2FfBKJfcZNyEt1n6` - **Finn:** Tenor pitched, excellent for podcasts and light chats
* `56AoDkrOh6qfVPDXZ7Pt` - **Cassidy:** Engaging and energetic, good for entertainment contexts
* `NOpBlnGInO9m6vDvFkFC` - **Grandpa Spuds Oxley:** Distinctive character voice for unique agents

## Voice settings

<Frame background="subtle">
  ![Voice settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/007b0ec153f9210ce48a6e6ed3184c4d004476222a2be2b5bf6ab6afdecf4804/assets/images/conversational-ai/voice-parameters.png)
</Frame>

Voice settings dramatically affect how your agent is perceived:

* **Stability:** Lower values (0.30-0.50) create more emotional, dynamic delivery but may occasionally sound unstable. Higher values (0.60-0.85) produce more consistent but potentially monotonous output.

* **Similarity:** Higher values will boost the overall clarity and consistency of the voice. Very high values may lead to sound distortions. Adjusting this value to find the right balance is recommended.

* **Speed:** Most natural conversations occur at 0.9-1.1x speed. Depending on the voice, adjust slower for complex topics or faster for routine information.

<Tip>
  Test your agent with different voice settings using the same prompt to find the optimal
  combination. Small adjustments can dramatically change the perceived personality of your agent.
</Tip>


# Language

> Learn how to configure your agent to speak multiple languages.

## Overview

This guide shows you how to configure your agent to speak multiple languages. You'll learn to:

* Configure your agent's primary language
* Add support for multiple languages
* Set language-specific voices and first messages
* Optimize voice selection for natural pronunciation
* Enable automatic language switching

## Guide

<Steps>
  <Step title="Default agent language">
    When you create a new agent, it's configured with:

    * English as the primary language
    * Flash v2 model for fast, English-only responses
    * A default first message.

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c533094b96146b19a31fd712a02a4b0b6d63790aa2168698e7dc682291c04e0b/assets/images/conversational-ai/language-overview.png)
    </Frame>

    <Note>
      Additional languages switch the agent to use the v2.5 Multilingual model. English will always use
      the v2 model.
    </Note>
  </Step>

  <Step title="Add additional languages">
    First, navigate to your agent's configuration page and locate the **Agent** tab.

    1. In the **Additional Languages** add an additional language (e.g. French)
    2. Review the first message, which is automatically translated using a Large Language Model (LLM). Customize it as needed for each additional language to ensure accuracy and cultural relevance.

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a5db1d23c7c1cc22b41f9093839cd76b078e6cbef69230714f8c0e58f3609b2f/assets/images/conversational-ai/language-selection.png)
    </Frame>

    <Note>
      Selecting the **All** option in the **Additional Languages** dropdown will configure the agent to
      support 31 languages. Collectively, these languages are spoken by approximately 90% of the world's
      population.
    </Note>
  </Step>

  <Step title="Configure language-specific voices">
    For optimal pronunciation, configure each additional language with a language-specific voice from our [Voice Library](https://elevenlabs.io/app/voice-library).

    <Note>
      To find great voices for each language curated by the ElevenLabs team, visit the [language top
      picks](https://elevenlabs.io/app/voice-library/collections).
    </Note>

    <Tabs>
      <Tab title="Language-specific voice settings">
        <Frame background="subtle">
          ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e1335d0fc8fe77691f00b928c9aeb5e050226a0d766dbab325ded52e97ed4399/assets/images/conversational-ai/language-voice.png)
        </Frame>
      </Tab>

      <Tab title="Voice library">
        <Frame background="subtle">
          ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/975e3c0207d86c06d4d68db0ef600ec6a716596062eabfec395b0356265f3583/assets/images/conversational-ai/voice-library-language.png)
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enable language detection">
    Add the [language detection tool](/docs/agents-platform/customization/tools/system-tools/language-detection) to your agent can automatically switch to the user's preferred language.
  </Step>

  <Step title="Starting a call">
    Now that the agent is configured to support additional languages, the widget will prompt the user for their preferred language before the conversation begins.

    If using the SDK, the language can be set programmatically using conversation overrides. See the
    [Overrides](/docs/agents-platform/customization/personalization/overrides) guide for implementation details.

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4252ccb78e8c03f864b3389ec641a296ec99b9e89ae7d7efe2de36ef6132a152/assets/images/conversational-ai/widget-language.png)
    </Frame>

    <Note>
      Language selection is fixed for the duration of the call - users cannot switch languages
      mid-conversation.
    </Note>
  </Step>
</Steps>

### Internationalization

You can integrate the widget with your internationalization framework by dynamically setting the language and UI text attributes.

```html title="Widget"
<elevenlabs-convai
  language="es"
  action-text={i18n["es"]["actionText"]}
  start-call-text={i18n["es"]["startCall"]}
  end-call-text={i18n["es"]["endCall"]}
  expand-text={i18n["es"]["expand"]}
  listening-text={i18n["es"]["listening"]}
  speaking-text={i18n["es"]["speaking"]}
></elevenlabs-convai>
```

<Note>
  Ensure the language codes match between your i18n framework and the agent's supported languages.
</Note>

## Best practices

<AccordionGroup>
  <Accordion title="Voice selection">
    Select voices specifically trained in your target languages. This ensures:

    * Natural pronunciation
    * Appropriate regional accents
    * Better handling of language-specific nuances
  </Accordion>

  <Accordion title="First message customization">
    While automatic translations are provided, consider:

    <div>
      * Reviewing translations for accuracy
      * Adapting greetings for cultural context
      * Adjusting formal/informal tone as needed
    </div>
  </Accordion>
</AccordionGroup>


# Knowledge base

> Enhance your conversational agent with custom knowledge.

**Knowledge bases** allow you to equip your agent with relevant, domain-specific information.

## Overview

A well-curated knowledge base helps your agent go beyond its pre-trained data and deliver context-aware answers.

Here are a few examples where knowledge bases can be useful:

* **Product catalogs**: Store product specifications, pricing, and other essential details.
* **HR or corporate policies**: Provide quick answers about vacation policies, employee benefits, or onboarding procedures.
* **Technical documentation**: Equip your agent with in-depth guides or API references to assist developers.
* **Customer FAQs**: Answer common inquiries consistently.

<Info>
  The agent on this page is configured with full knowledge of ElevenLabs' documentation and sitemap. Go ahead and ask it about anything about ElevenLabs.
</Info>

## Usage

<Tabs>
  <Tab title="Build a knowledge base via the API">
    <CodeBlocks>
      ```python
      # First create the document from text
      knowledge_base_document_text = elevenlabs.conversational_ai.knowledge_base.documents.create_from_text(
          text="The airspeed velocity of an unladen swallow (European) is 24 miles per hour or roughly 11 meters per second.",
          name="Unladen Swallow facts",
      )

      # Alternatively, you can create a document from a URL
      knowledge_base_document_url = elevenlabs.conversational_ai.knowledge_base.documents.create_from_url(
          url="https://en.wikipedia.org/wiki/Unladen_swallow",
          name="Unladen Swallow Wikipedia page",
      )

      # Or create a document from a file
      knowledge_base_document_file = elevenlabs.conversational_ai.knowledge_base.documents.create_from_file(
          file=open("/path/to/unladen-swallow-facts.txt", "rb"),
          name="Unladen Swallow Facts",
      )

      # Then add the document to the agent
      agent = elevenlabs.conversational_ai.agents.update(
          agent_id="agent-id",
          conversation_config={
              "agent": {
                  "prompt": {
                      "knowledge_base": [
                          {
                              "type": "text",
                              "name": knowledge_base_document_text.name,
                              "id": knowledge_base_document_text.id,
                          },
                          {
                              "type": "url",
                              "name": knowledge_base_document_url.name,
                              "id": knowledge_base_document_url.id,
                          },
                          {
                              "type": "file",
                              "name": knowledge_base_document_file.name,
                              "id": knowledge_base_document_file.id,
                          }
                      ]
                  }
              }
          },
      )

      print("Agent updated:", agent)
      ```

      ```typescript
      import fs from "node:fs";

      // First create the document from text
      const knowledgeBaseDocumentText = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromText({
        name: "Unladen Swallow Facts",
        text: "The airspeed velocity of an unladen swallow (European) is 24 miles per hour or roughly 11 meters per second.",
      });

      // Alternatively, you can create a document from a URL
      const knowledgeBaseDocumentUrl = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromUrl({
        name: "Unladen Swallow Facts",
        url: "https://en.wikipedia.org/wiki/Unladen_swallow",
      });

      // Or create a document from a file
      const fileBuffer = fs.readFileSync("/path/to/unladen-swallow-facts.txt");
      const file = new File([fileBuffer], "unladen-swallow-facts.txt", { type: "text/plain" });

      const knowledgeBaseDocumentFile = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromFile({
        name: "Unladen Swallow Facts",
        file: file,
      });

      // Then add the document to the agent
      const agent = await elevenlabs.conversationalAi.agents.update("agent-id", {
          conversationConfig: {
              agent: {
                  prompt: {
                      knowledgeBase: [
                          {
                              type: "text",
                              name: knowledgeBaseDocumentText.name,
                              id: knowledgeBaseDocumentText.id,
                          },
                          {
                              type: "url",
                              name: knowledgeBaseDocumentUrl.name,
                              id: knowledgeBaseDocumentUrl.id,
                          },
                          {
                              type: "file",
                              name: knowledgeBaseDocumentFile.name,
                              id: knowledgeBaseDocumentFile.id,
                          }
                      ]
                  }
              }
          }
      });

      console.log("Agent updated:", agent);
      ```
    </CodeBlocks>
  </Tab>

  <Tab title="Build a knowledge base via the web dashboard">
    Files, URLs, and text can be added to the knowledge base in the dashboard.

    <Steps>
      <Step title="File">
        Upload files in formats like PDF, TXT, DOCX, HTML, and EPUB.

        <Frame background="subtle">
          ![File upload interface showing supported formats (PDF, TXT, DOCX, HTML, EPUB) with a 21MB
          size limit](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/03218c6faaf2a65e8f93c6b0d0528db3b600944840b43c05d5518ed2db6a2630/assets/images/conversational-ai/knowledge-file.jpg)
        </Frame>
      </Step>

      <Step title="URL">
        Import URLs from sources like documentation and product pages.

        <Frame background="subtle">
          ![URL import interface where users can paste documentation
          links](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d100cbb5c15768d5f5f1880f07be9b59e04dcc68eaaa81bae3c58ca6d651f098/assets/images/conversational-ai/knowledge-url.jpg)
        </Frame>

        <Note>
          When creating a knowledge base item from a URL, we do not currently support scraping all pages
          linked to from the initial URL, or continuously updating the knowledge base over time.
          However, these features are coming soon.
        </Note>

        <Warning>
          Ensure you have permission to use the content from the URLs you provide
        </Warning>
      </Step>

      <Step title="Text">
        Manually add text to the knowledge base.

        <Frame background="subtle">
          ![Text input interface where users can name and add custom
          content](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3db67ebc9c6fa40f1ad0ec9b60fc48abe08196cadb52aaf3d56dacc476034e75/assets/images/conversational-ai/knowledge-text.jpg)
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Best practices

<h4>
  Content quality
</h4>

Provide clear, well-structured information that's relevant to your agent's purpose.

<h4>
  Size management
</h4>

Break large documents into smaller, focused pieces for better processing.

<h4>
  Regular updates
</h4>

Regularly review and update the agent's knowledge base to ensure the information remains current and accurate.

<h4>
  Identify knowledge gaps
</h4>

Review conversation transcripts to identify popular topics, queries and areas where users struggle to find information. Note any knowledge gaps and add the missing context to the knowledge base.

## Enterprise features

Non-enterprise accounts have a maximum of 20MB or 300k characters.

<Info>
  Need higher limits? [Contact our sales team](https://elevenlabs.io/contact-sales) to discuss
  enterprise plans with expanded knowledge base capabilities.
</Info>


# Knowledge base dashboard

> Learn how to manage and organize your knowledge base through the ElevenLabs dashboard

## Overview

The [knowledge base dashboard](https://elevenlabs.io/app/agents/knowledge-base) provides a centralized way to manage documents and track their usage across your AI agents. This guide explains how to navigate and use the knowledge base dashboard effectively.

<Frame background="subtle">
  ![Knowledge base main interface showing list of
  documents](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d0c15168af40c776865e2ef48c39234287e30eeeb2752c74083704749074924f/assets/images/conversational-ai/kb-content.png)
</Frame>

## Adding existing documents to agents

When configuring an agent's knowledge base, you can easily add existing documents to an agent.

1. Navigate to the agent's [configuration](https://elevenlabs.io/app/agents/)
2. Click "Add document" in the knowledge base section of the "Agent" tab.
3. The option to select from your existing knowledge base documents or upload a new document will appear.

<Frame background="subtle">
  ![Interface for adding documents to an
  agent](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8eda3a9e686e87705e0d1f1e82a9d01b4960a2c00f597253995b589421650995/assets/images/conversational-ai/kb-add-doc-items.png)
</Frame>

<Tip>
  Documents can be reused across multiple agents, making it efficient to maintain consistent
  knowledge across your workspace.
</Tip>

## Document dependencies

Each document in your knowledge base includes a "Agents" tab that shows which agents currently depend on that document.

<Frame background="subtle">
  ![Dependent agents tab showing which agents use a
  document](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6bed2a22b4ea13dc6e1048b94398c5dd438fc5fed87ca27e575c4351c83181de/assets/images/conversational-ai/kb-dependent-agents.png)
</Frame>

It is not possible to delete a document if any agent depends on it.


# Retrieval-Augmented Generation

> Enhance your agent with large knowledge bases using RAG.

## Overview

**Retrieval-Augmented Generation (RAG)** enables your agent to access and use large knowledge bases during conversations. Instead of loading entire documents into the context window, RAG retrieves only the most relevant information for each user query, allowing your agent to:

* Access much larger knowledge bases than would fit in a prompt
* Provide more accurate, knowledge-grounded responses
* Reduce hallucinations by referencing source material
* Scale knowledge without creating multiple specialized agents

RAG is ideal for agents that need to reference large documents, technical manuals, or extensive
knowledge bases that would exceed the context window limits of traditional prompting.
RAG adds on slight latency to the response time of your agent, around 500ms.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/aFeJO7W0DIk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## How RAG works

When RAG is enabled, your agent processes user queries through these steps:

1. **Query processing**: The user's question is analyzed and reformulated for optimal retrieval.
2. **Embedding generation**: The processed query is converted into a vector embedding that represents the user's question.
3. **Retrieval**: The system finds the most semantically similar content from your knowledge base.
4. **Response generation**: The agent generates a response using both the conversation context and the retrieved information.

This process ensures that relevant information to the user's query is passed to the LLM to generate a factually correct answer.

## Guide

### Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs [Conversational Agent](/docs/agents-platform/quickstart)
* At least one document added to your agent's knowledge base

<Steps>
  <Step title="Enable RAG for your agent">
    In your agent's settings, navigate to the **Knowledge Base** section and toggle on the **Use RAG** option.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/bdcdf9c15b8eb653248909e11149d0c383fb45f761f3bfbc47ba56feb25d8899/assets/images/conversational-ai/rag-enabled.png" alt="Toggle switch to enable RAG in the agent settings" />
    </Frame>
  </Step>

  <Step title="Configure RAG settings (optional)">
    After enabling RAG, you'll see additional configuration options in the **Advanced** tab:

    * **Embedding model**: Select the model that will convert text into vector embeddings
    * **Maximum document chunks**: Set the maximum amount of retrieved content per query
    * **Maximum vector distance**: Set the maximum distance between the query and the retrieved chunks

    These parameters could impact latency. They also could impact LLM cost.
    For example, retrieving more chunks increases cost.
    Increasing vector distance allows for more context to be passed, but potentially less relevant context.
    This may affect quality and you should experiment with different parameters to find the best results.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c9a0f81555c8fadd0324637c672f08950889e19b9cf56f971d60fcc520a06d0a/assets/images/conversational-ai/rag-config.png" alt="RAG configuration options including embedding model selection" />
    </Frame>
  </Step>

  <Step title="Knowledge base indexing">
    Each document in your knowledge base needs to be indexed before it can be used with RAG. This
    process happens automatically when a document is added to an agent with RAG enabled.

    <Info>
      Indexing may take a few minutes for large documents. You can check the indexing status in the
      knowledge base list.
    </Info>
  </Step>

  <Step title="Configure document usage modes (optional)">
    For each document in your knowledge base, you can choose how it's used:

    * **Auto (default)**: The document is only retrieved when relevant to the query
    * **Prompt**: The document is always included in the system prompt, regardless of relevance, but can also be retrieved by RAG

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fb47404f1ac2a698ed9dfedaa5bd75ea9d4b00c701a97e8db0caec8d18ef60ce/assets/images/conversational-ai/rag-prompt.png" alt="Document usage mode options in the knowledge base" />
    </Frame>

    <Warning>
      Setting too many documents to "Prompt" mode may exceed context limits. Use this option sparingly
      for critical information.
    </Warning>
  </Step>

  <Step title="Test your RAG-enabled agent">
    After saving your configuration, test your agent by asking questions related to your knowledge base. The agent should now be able to retrieve and reference specific information from your documents.
  </Step>
</Steps>

## Usage limits

To ensure fair resource allocation, ElevenLabs enforces limits on the total size of documents that can be indexed for RAG per workspace, based on subscription tier.

The limits are as follows:

| Subscription Tier | Total Document Size Limit | Notes                                                |
| :---------------- | :------------------------ | :--------------------------------------------------- |
| Free              | 1MB                       | Indexes may be deleted after inactivity.             |
| Starter           | 2MB                       |                                                      |
| Creator           | 20MB                      |                                                      |
| Pro               | 100MB                     |                                                      |
| Scale             | 500MB                     |                                                      |
| Business          | 1GB                       |                                                      |
| Enterprise        | 1GB                       | Higher limits available based on tier and agreement. |

**Note:**

* These limits apply to the total **original file size** of documents indexed for RAG, not the internal storage size of the RAG index itself (which can be significantly larger).
* Documents smaller than 500 bytes cannot be indexed for RAG and will automatically be used in the prompt instead.

## API implementation

You can also implement RAG through the [API](/docs/api-reference/knowledge-base/compute-rag-index):

<CodeBlocks>
  ```python
  from elevenlabs import ElevenLabs
  import time

  # Initialize the ElevenLabs client
  elevenlabs = ElevenLabs(api_key="your-api-key")

  # First, index a document for RAG
  document_id = "your-document-id"
  embedding_model = "e5_mistral_7b_instruct"

  # Trigger RAG indexing
  response = elevenlabs.conversational_ai.knowledge_base.document.compute_rag_index(
      documentation_id=document_id,
      model=embedding_model
  )

  # Check indexing status
  while response.status not in ["SUCCEEDED", "FAILED"]:
      time.sleep(5)  # Wait 5 seconds before checking status again
      response = elevenlabs.conversational_ai.knowledge_base.document.compute_rag_index(
          documentation_id=document_id,
          model=embedding_model
      )

  # Then update agent configuration to use RAG
  agent_id = "your-agent-id"

  # Get the current agent configuration
  agent_config = elevenlabs.conversational_ai.agents.get(agent_id=agent_id)

  # Enable RAG in the agent configuration
  agent_config.agent.prompt.rag = {
      "enabled": True,
      "embedding_model": "e5_mistral_7b_instruct",
      "max_documents_length": 10000
  }

  # Update document usage mode if needed
  for i, doc in enumerate(agent_config.agent.prompt.knowledge_base):
      if doc.id == document_id:
          agent_config.agent.prompt.knowledge_base[i].usage_mode = "auto"

  # Update the agent configuration
  elevenlabs.conversational_ai.agents.update(
      agent_id=agent_id,
      conversation_config=agent_config.agent
  )

  ```

  ```javascript
  // First, index a document for RAG
  async function enableRAG(documentId, agentId, apiKey) {
    try {
      // Initialize the ElevenLabs client
      const { ElevenLabs } = require('elevenlabs');
      const elevenlabs = new ElevenLabs({
        apiKey: apiKey,
      });

      // Start document indexing for RAG
      let response = await elevenlabs.conversationalAi.knowledgeBase.document.computeRagIndex(
        documentId,
        {
          model: 'e5_mistral_7b_instruct',
        }
      );

      // Check indexing status until completion
      while (response.status !== 'SUCCEEDED' && response.status !== 'FAILED') {
        await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5 seconds
        response = await elevenlabs.conversationalAi.knowledgeBase.document.computeRagIndex(
          documentId,
          {
            model: 'e5_mistral_7b_instruct',
          }
        );
      }

      if (response.status === 'FAILED') {
        throw new Error('RAG indexing failed');
      }

      // Get current agent configuration
      const agentConfig = await elevenlabs.conversationalAi.agents.get(agentId);

      // Enable RAG in the agent configuration
      const updatedConfig = {
        conversation_config: {
          ...agentConfig.agent,
          prompt: {
            ...agentConfig.agent.prompt,
            rag: {
              enabled: true,
              embedding_model: 'e5_mistral_7b_instruct',
              max_documents_length: 10000,
            },
          },
        },
      };

      // Update document usage mode if needed
      if (agentConfig.agent.prompt.knowledge_base) {
        agentConfig.agent.prompt.knowledge_base.forEach((doc, index) => {
          if (doc.id === documentId) {
            updatedConfig.conversation_config.prompt.knowledge_base[index].usage_mode = 'auto';
          }
        });
      }

      // Update the agent configuration
      await elevenlabs.conversationalAi.agents.update(agentId, updatedConfig);

      console.log('RAG configuration updated successfully');
      return true;
    } catch (error) {
      console.error('Error configuring RAG:', error);
      throw error;
    }
  }

  // Example usage
  // enableRAG('your-document-id', 'your-agent-id', 'your-api-key')
  //   .then(() => console.log('RAG setup complete'))
  //   .catch(err => console.error('Error:', err));
  ```
</CodeBlocks>


# Tools

> Enhance ElevenLabs agents with custom functionalities and external integrations.

## Overview

Tools allow ElevenLabs agents to perform actions beyond generating text responses.
They enable agents to interact with external systems, execute custom logic, or access specific functionalities during a conversation.
This allows for richer, more capable interactions tailored to specific use cases.

ElevenLabs Agents supports the following kinds of tools:

<CardGroup cols={2}>
  <Card title="Client Tools" href="/agents-platform/customization/tools/client-tools" icon="rectangle-code">
    Tools executed directly on the client-side application (e.g., web browser, mobile app).
  </Card>

  <Card title="Server Tools" href="/agents-platform/customization/tools/server-tools" icon="server">
    Custom tools executed on your server-side infrastructure via API calls.
  </Card>

  <Card title="MCP Tools" href="/agents-platform/customization/tools/mcp" icon="plug">
    Model Context Protocol servers that provide tools and resources to agents.
  </Card>

  <Card title="System Tools" href="/agents-platform/customization/tools/system-tools" icon="computer-classic">
    Built-in tools provided by the platform for common actions.
  </Card>
</CardGroup>

## Tool Features

<CardGroup cols={2}>
  <Card title="Tool Call Sounds" href="/agents-platform/customization/tools/tool-configuration/tool-call-sounds" icon="volume">
    Add ambient audio during tool execution to enhance user experience.
  </Card>
</CardGroup>


# Client tools

> Empower your assistant to trigger client-side operations.

**Client tools** enable your assistant to execute client-side functions. Unlike [server-side tools](/docs/agents-platform/customization/tools), client tools allow the assistant to perform actions such as triggering browser events, running client-side functions, or sending notifications to a UI.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/XeDT92mR7oE?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Applications may require assistants to interact directly with the user's environment. Client-side tools give your assistant the ability to perform client-side operations.

Here are a few examples where client tools can be useful:

* **Triggering UI events**: Allow an assistant to trigger browser events, such as alerts, modals or notifications.
* **Interacting with the DOM**: Enable an assistant to manipulate the Document Object Model (DOM) for dynamic content updates or to guide users through complex interfaces.

<Info>
  To perform operations server-side, use
  [server-tools](/docs/agents-platform/customization/tools/server-tools) instead.
</Info>

## Guide

### Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs Conversational Agent ([create one here](https://elevenlabs.io/app/agents))

<Steps>
  <Step title="Create a new client-side tool">
    Navigate to your agent dashboard. In the **Tools** section, click **Add Tool**. Ensure the **Tool Type** is set to **Client**. Then configure the following:

    | Setting     | Parameter                                                        |
    | ----------- | ---------------------------------------------------------------- |
    | Name        | logMessage                                                       |
    | Description | Use this client-side tool to log a message to the user's client. |

    Then create a new parameter `message` with the following configuration:

    | Setting     | Parameter                                                                          |
    | ----------- | ---------------------------------------------------------------------------------- |
    | Data Type   | String                                                                             |
    | Identifier  | message                                                                            |
    | Required    | true                                                                               |
    | Description | The message to log in the console. Ensure the message is informative and relevant. |

    <Frame background="subtle">
      ![logMessage client-tool setup](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12/assets/images/conversational-ai/client-tool-example.jpg)
    </Frame>
  </Step>

  <Step title="Register the client tool in your code">
    Unlike server-side tools, client tools need to be registered in your code.

    Use the following code to register the client tool:

    <CodeBlocks>
      ```python title="Python" focus={4-16}
      from elevenlabs import ElevenLabs
      from elevenlabs.conversational_ai.conversation import Conversation, ClientTools

      def log_message(parameters):
          message = parameters.get("message")
          print(message)

      client_tools = ClientTools()
      client_tools.register("logMessage", log_message)

      conversation = Conversation(
          client=ElevenLabs(api_key="your-api-key"),
          agent_id="your-agent-id",
          client_tools=client_tools,
          # ...
      )

      conversation.start_session()
      ```

      ```javascript title="JavaScript" focus={2-10}
      // ...
      const conversation = await Conversation.startSession({
        // ...
        clientTools: {
          logMessage: async ({message}) => {
            console.log(message);
          }
        },
        // ...
      });
      ```

      ```swift title="Swift" focus={2-10}
      // ...
      var clientTools = ElevenLabsSDK.ClientTools()

      clientTools.register("logMessage") { parameters async throws -> String? in
          guard let message = parameters["message"] as? String else {
              throw ElevenLabsSDK.ClientToolError.invalidParameters
          }
          print(message)
          return message
      }
      ```
    </CodeBlocks>

    <Note>
      The tool and parameter names in the agent configuration are case-sensitive and **must** match those registered in your code.
    </Note>
  </Step>

  <Step title="Testing">
    Initiate a conversation with your agent and say something like:

    > *Log a message to the console that says Hello World*

    You should see a `Hello World` log appear in your console.
  </Step>

  <Step title="Next steps">
    Now that you've set up a basic client-side event, you can:

    * Explore more complex client tools like opening modals, navigating to pages, or interacting with the DOM.
    * Combine client tools with server-side webhooks for full-stack interactions.
    * Use client tools to enhance user engagement and provide real-time feedback during conversations.
  </Step>
</Steps>

### Passing client tool results to the conversation context

When you want your agent to receive data back from a client tool, ensure that you tick the **Wait for response** option in the tool configuration.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e/assets/images/conversational-ai/wait-until-tool-result.png" alt="Wait for response option in client tool configuration" />
</Frame>

Once the client tool is added, when the function is called the agent will wait for its response and append the response to the conversation context.

<CodeBlocks>
  ```python title="Python"
  def get_customer_details():
      # Fetch customer details (e.g., from an API or database)
      customer_data = {
          "id": 123,
          "name": "Alice",
          "subscription": "Pro"
      }
      # Return the customer data; it can also be a JSON string if needed.
      return customer_data

  client_tools = ClientTools()
  client_tools.register("getCustomerDetails", get_customer_details)

  conversation = Conversation(
      client=ElevenLabs(api_key="your-api-key"),
      agent_id="your-agent-id",
      client_tools=client_tools,
      # ...
  )

  conversation.start_session()
  ```

  ```javascript title="JavaScript"
  const clientTools = {
    getCustomerDetails: async () => {
      // Fetch customer details (e.g., from an API)
      const customerData = {
        id: 123,
        name: "Alice",
        subscription: "Pro"
      };
      // Return data directly to the agent.
      return customerData;
    }
  };

  // Start the conversation with client tools configured.
  const conversation = await Conversation.startSession({ clientTools });
  ```
</CodeBlocks>

In this example, when the agent calls **getCustomerDetails**, the function will execute on the client and the agent will receive the returned data, which is then used as part of the conversation context. The values from the response can also optionally be assigned to dynamic variables, similar to [server tools](https://elevenlabs.io/docs/agents-platform/customization/tools/server-tools). Note system tools cannot update dynamic variables.

### Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not being triggered">
    * Ensure the tool and parameter names in the agent configuration match those registered in your code.
    * View the conversation transcript in the agent dashboard to verify the tool is being executed.
  </Accordion>

  <Accordion title="Console errors">
    * Open the browser console to check for any errors.
    * Ensure that your code has necessary error handling for undefined or unexpected parameters.
  </Accordion>
</AccordionGroup>

## Best practices

<h4>
  Name tools intuitively, with detailed descriptions
</h4>

If you find the assistant does not make calls to the correct tools, you may need to update your tool names and descriptions so the assistant more clearly understands when it should select each tool. Avoid using abbreviations or acronyms to shorten tool and argument names.

You can also include detailed descriptions for when a tool should be called. For complex tools, you should include descriptions for each of the arguments to help the assistant know what it needs to ask the user to collect that argument.

<h4>
  Name tool parameters intuitively, with detailed descriptions
</h4>

Use clear and descriptive names for tool parameters. If applicable, specify the expected format for a parameter in the description (e.g., YYYY-mm-dd or dd/mm/yy for a date).

<h4>
  Consider providing additional information about how and when to call tools in your assistant's
  system prompt
</h4>

Providing clear instructions in your system prompt can significantly improve the assistant's tool calling accuracy. For example, guide the assistant with instructions like the following:

```plaintext
Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.
```

Provide context for complex scenarios. For example:

```plaintext
Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.
```

<h4>
  LLM selection
</h4>

<Warning>
  When using tools, we recommend picking high intelligence models like GPT-4o mini or Claude 3.5
  Sonnet and avoiding Gemini 1.5 Flash.
</Warning>

It's important to note that the choice of LLM matters to the success of function calls. Some LLMs can struggle with extracting the relevant parameters from the conversation.


# Server tools

> Connect your assistant to external data & systems.

**Tools** enable your assistant to connect to external data and systems. You can define a set of tools that the assistant has access to, and the assistant will use them where appropriate based on the conversation.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/pB33QxKN8P8?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Many applications require assistants to call external APIs to get real-time information. Tools give your assistant the ability to make external function calls to third party apps so you can get real-time information.

Here are a few examples where tools can be useful:

* **Fetching data**: enable an assistant to retrieve real-time data from any REST-enabled database or 3rd party integration before responding to the user.
* **Taking action**: allow an assistant to trigger authenticated actions based on the conversation, like scheduling meetings or initiating order returns.

<Info>
  To interact with Application UIs or trigger client-side events use [client
  tools](/docs/agents-platform/customization/tools/client-tools) instead.
</Info>

## Tool configuration

ElevenLabs agents can be equipped with tools to interact with external APIs. Unlike traditional requests, the assistant generates query, body, and path parameters dynamically based on the conversation and parameter descriptions you provide.

All tool configurations and parameter descriptions help the assistant determine **when** and **how** to use these tools. To orchestrate tool usage effectively, update the assistant’s system prompt to specify the sequence and logic for making these calls. This includes:

* **Which tool** to use and under what conditions.
* **What parameters** the tool needs to function properly.
* **How to handle** the responses.

<br />

<Tabs>
  <Tab title="Configuration">
    Define a high-level `Name` and `Description` to describe the tool's purpose. This helps the LLM understand the tool and know when to call it.

    <Info>
      If the API requires path parameters, include variables in the URL path by wrapping them in curly
      braces `{}`, for example: `/api/resource/{id}` where `id` is a path parameter.
    </Info>

    <Frame background="subtle">
      ![Configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5/assets/images/conversational-ai/tool-configuration.jpg)
    </Frame>
  </Tab>

  <Tab title="Authentication">
    Configure authentication by adding custom headers or using out-of-the-box authentication methods through auth connections.

    <Frame background="subtle">
      ![Tool authentication](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630/assets/images/conversational-ai/tool-secrets.jpg)
    </Frame>
  </Tab>

  <Tab title="Headers">
    Specify any headers that need to be included in the request.

    <Frame background="subtle">
      ![Headers](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66/assets/images/conversational-ai/tool-headers.jpg)
    </Frame>
  </Tab>

  <Tab title="Path parameters">
    Include variables in the URL path by wrapping them in curly braces `{}`:

    * **Example**: `/api/resource/{id}` where `id` is a path parameter.

    <Frame background="subtle">
      ![Path parameters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d/assets/images/conversational-ai/tool-path-parameters.jpg)
    </Frame>
  </Tab>

  <Tab title="Body parameters">
    Specify any body parameters to be included in the request.

    <Frame background="subtle">
      ![Body parameters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205/assets/images/conversational-ai/tool-body-parameters.jpg)
    </Frame>
  </Tab>

  <Tab title="Query parameters">
    Specify any query parameters to be included in the request.

    <Frame background="subtle">
      ![Query parameters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e/assets/images/conversational-ai/tool-query-parameters.jpg)
    </Frame>
  </Tab>

  <Tab title="Dynamic variable assignment">
    Specify dynamic variables to update from the tool response for later use in the conversation.

    <Frame background="subtle">
      ![Query parameters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110/assets/images/conversational-ai/dv-assignment.png)
    </Frame>
  </Tab>
</Tabs>

## Guide

In this guide, we'll create a weather assistant that can provide real-time weather information for any location. The assistant will use its geographic knowledge to convert location names into coordinates and fetch accurate weather data.

<div>
  <iframe src="https://player.vimeo.com/video/1061374724?h=bd9bdb535e&badge=0&autopause=0&player_id=0&app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media" title="weatheragent" />
</div>

<Steps>
  <Step title="Configure the weather tool">
    First, on the **Agent** section of your agent settings page, choose **Add Tool**. Select **Webhook** as the Tool Type, then configure the weather API integration:

    <AccordionGroup>
      <Accordion title="Weather Tool Configuration">
        <Tabs>
          <Tab title="Configuration">
            | Field       | Value                                                                                                                                                                                                                                                                                                                                                                                  |
            | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
            | Name        | get\_weather                                                                                                                                                                                                                                                                                                                                                                           |
            | Description | Gets the current weather forecast for a location                                                                                                                                                                                                                                                                                                                                       |
            | Method      | GET                                                                                                                                                                                                                                                                                                                                                                                    |
            | URL         | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\&current=temperature\_2m,wind\_speed\_10m\&hourly=temperature\_2m,relative\_humidity\_2m,wind\_speed\_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\&current=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) |
          </Tab>

          <Tab title="Path Parameters">
            | Data Type | Identifier | Value Type | Description                                         |
            | --------- | ---------- | ---------- | --------------------------------------------------- |
            | string    | latitude   | LLM Prompt | The latitude coordinate for the requested location  |
            | string    | longitude  | LLM Prompt | The longitude coordinate for the requested location |
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>

    <Warning>
      An API key is not required for this tool. If one is required, this should be passed in the headers and stored as a secret.
    </Warning>
  </Step>

  <Step title="Orchestration">
    Configure your assistant to handle weather queries intelligently with this system prompt:

    ```plaintext System prompt
    You are a helpful conversational agent with access to a weather tool. When users ask about
    weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires
    a latitude and longitude - use your geographic knowledge to convert location names to coordinates
    accurately.

    Never ask users for coordinates - you must determine these yourself. Always report weather
    information conversationally, referring to locations by name only. For weather requests:

    1. Extract the location from the user's message
    2. Convert the location to coordinates and call get_weather
    3. Present the information naturally and helpfully

    For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be
    concise, accurate, and helpful.

    First message: "Hey, how can I help you today?"
    ```

    <Success>
      Test your assistant by asking about the weather in different locations. The assistant should
      handle specific locations ("What's the weather in Tokyo?") and ask for clarification after general queries ("How's
      the weather looking today?").
    </Success>
  </Step>
</Steps>

## Supported Authentication Methods

ElevenLabs Agents supports multiple authentication methods to securely connect your tools with external APIs. Authentication methods are configured in your agent settings and then connected to individual tools as needed.

<Frame background="subtle">
  ![Workspace Auth Connection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1/assets/images/conversational-ai/workspace-auth-connection.png)
</Frame>

Once configured, you can connect these authentication methods to your tools and manage custom headers in the tool configuration:

<Frame background="subtle">
  ![Tool Auth Connection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9/assets/images/conversational-ai/tool-auth-config.png)
</Frame>

#### OAuth2 Client Credentials

Automatically handles the OAuth2 client credentials flow. Configure with your client ID, client secret, and token URL (e.g., `https://api.example.com/oauth/token`). Optionally specify scopes as comma-separated values and additional JSON parameters. Set up by clicking **Add Auth** on **Workspace Auth Connections** on the **Agent** section of your agent settings page.

#### OAuth2 JWT

Uses JSON Web Token authentication for OAuth 2.0 JWT Bearer flow. Requires your JWT signing secret, token URL, and algorithm (default: HS256). Configure JWT claims including issuer, audience, and subject. Optionally set key ID, expiration (default: 3600 seconds), scopes, and extra parameters. Set up by clicking **Add Auth** on **Workspace Auth Connections** on the **Agent** section of your agent settings page.

#### Basic Authentication

Simple username and password authentication for APIs that support HTTP Basic Auth. Set up by clicking **Add Auth** on **Workspace Auth Connections** in the **Agent** section of your agent settings page.

#### Bearer Tokens

Token-based authentication that adds your bearer token value to the request header. Configure by adding a header to the tool configuration, selecting **Secret** as the header type, and clicking **Create New Secret**.

#### Custom Headers

Add custom authentication headers with any name and value for proprietary authentication methods. Configure by adding a header to the tool configuration and specifying its **name** and **value**.

## Best practices

<h4>
  Name tools intuitively, with detailed descriptions
</h4>

If you find the assistant does not make calls to the correct tools, you may need to update your tool names and descriptions so the assistant more clearly understands when it should select each tool. Avoid using abbreviations or acronyms to shorten tool and argument names.

You can also include detailed descriptions for when a tool should be called. For complex tools, you should include descriptions for each of the arguments to help the assistant know what it needs to ask the user to collect that argument.

<h4>
  Name tool parameters intuitively, with detailed descriptions
</h4>

Use clear and descriptive names for tool parameters. If applicable, specify the expected format for a parameter in the description (e.g., YYYY-mm-dd or dd/mm/yy for a date).

<h4>
  Consider providing additional information about how and when to call tools in your assistant's
  system prompt
</h4>

Providing clear instructions in your system prompt can significantly improve the assistant's tool calling accuracy. For example, guide the assistant with instructions like the following:

```plaintext
Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.
```

Provide context for complex scenarios. For example:

```plaintext
Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.
```

<h4>
  LLM selection
</h4>

<Warning>
  When using tools, we recommend picking high intelligence models like GPT-4o mini or Claude 3.5
  Sonnet and avoiding Gemini 1.5 Flash.
</Warning>

It's important to note that the choice of LLM matters to the success of function calls. Some LLMs can struggle with extracting the relevant parameters from the conversation.

## Tool Call Sounds

You can configure ambient audio to play during tool execution to enhance the user experience. Learn more about [Tool Call Sounds](/agents-platform/customization/tools/tool-configuration/tool-call-sounds).


# Model Context Protocol

> Connect your ElevenLabs conversational agents to external tools and data sources using the Model Context Protocol.

<Error title="User Responsibility">
  You are responsible for the security, compliance, and behavior of any third-party MCP server you
  integrate with your ElevenLabs conversational agents. ElevenLabs provides the platform for
  integration but does not manage, endorse, or secure external MCP servers.
</Error>

## Overview

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that defines how applications provide context to Large Language Models (LLMs). Think of MCP as a universal connector that enables AI models to seamlessly interact with diverse data sources and tools. By integrating servers that implement MCP, you can significantly extend the capabilities of your ElevenLabs conversational agents.

<Frame background="subtle">
  <iframe width="100%" height="400" src="https://www.youtube.com/embed/m1HgNvafID8" title="ElevenLabs Model Context Protocol integration" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

<Note>
  MCP support is not currently available for users on Zero Retention Mode or those requiring HIPAA
  compliance.
</Note>

ElevenLabs allows you to connect your conversational agents to external MCP servers. This enables your agents to:

* Access and process information from various data sources via the MCP server
* Utilize specialized tools and functionalities exposed by the MCP server
* Create more dynamic, knowledgeable, and interactive conversational experiences

## Getting started

<Note>
  ElevenLabs supports both SSE (Server-Sent Events) and HTTP streamable transport MCP servers.
</Note>

1. Retrieve the URL of your MCP server. In this example, we'll use [Zapier MCP](https://zapier.com/mcp), which lets you connect ElevenAgents to hundreds of tools and services.

2. Navigate to the [MCP server integrations dashboard](https://elevenlabs.io/app/agents/integrations) and click "Add Custom MCP Server".

   <Frame background="subtle">
     ![Creating your first MCP server](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/335d1d8fced3cd82eed4ed43ba0058d3a8dbc431f81cdb387bf3d5964e5ead80/assets/images/conversational-ai/mcp-create.png)
   </Frame>

3. Configure the MCP server with the following details:

   * **Name**: The name of the MCP server (e.g., "Zapier MCP Server")
   * **Description**: A description of what the MCP server can do (e.g., "An MCP server with access to Zapier's tools and services")
   * **Server URL**: The URL of the MCP server. In some cases this contains a secret key, treat it like a password and store it securely as a workspace secret.
   * **Secret Token (Optional)**: If the MCP server requires a secret token (Authorization header), enter it here.
   * **HTTP Headers (Optional)**: If the MCP server requires additional HTTP headers, enter them here.

4. Click "Add Integration" to save the integration and test the connection to list available tools.

   <Frame background="subtle">
     ![Zapier example tools](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7c9d83baedd0e2dc74014d4a690159333bbef0eec37c36fa9ee0fd6cd455df0e/assets/images/conversational-ai/mcp-zapier.png)
   </Frame>

5. The MCP server is now available to add to your agents. MCP support is available for both public and private agents.

   <Frame background="subtle">
     ![Adding the MCP server to an agent](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b18756710b4466a5fa462080d6f3b237d84f76f898d5c94d4583f31d2fa0395b/assets/images/conversational-ai/mcp-add.png)
   </Frame>

## Tool approval modes

ElevenLabs provides flexible approval controls to manage how agents request permission to use tools from MCP servers. You can configure approval settings at both the MCP server level and individual tool level for maximum security control.

<Frame background="subtle">
  ![Tool approval mode settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9f4c208459131622478de5010e2234d3af8a03dc9bc5b7ec2fcab48a7be3bde3/assets/images/conversational-ai/mcp-approval.png)
</Frame>

### Available approval modes

* **Always Ask (Recommended)**: Maximum security. The agent will request your permission before each tool use.
* **Fine-Grained Tool Approval**: Disable and pre-select tools which can run automatically and those requiring approval.
* **No Approval**: The assistant can use any tool without approval.

### Fine-grained tool control

The Fine-Grained Tool Approval mode allows you to configure individual tools with different approval requirements, giving you precise control over which tools can run automatically and which require explicit permission.

<Frame background="subtle">
  ![Fine-grained tool approval
  settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/041cad753319ed92189ee8d4f70a9d3ed07177303bf71777ce36a90270a5dd24/assets/images/conversational-ai/mcp-finegrained-approvals.png)
</Frame>

For each tool, you can set:

* **Auto-approved**: Tool runs automatically without requiring permission
* **Requires approval**: Tool requires explicit permission before execution
* **Disabled**: Tool is completely disabled and cannot be used

<Tip>
  Use Fine-Grained Tool Approval to allow low-risk read-only tools to run automatically while
  requiring approval for tools that modify data or perform sensitive operations.
</Tip>

## Key considerations for ElevenLabs integration

* **External servers**: You are responsible for selecting the external MCP servers you wish to integrate. ElevenLabs provides the means to connect to them.
* **Supported features**: ElevenLabs supports MCP servers that communicate over SSE (Server-Sent Events) and HTTP streamable transports for real-time interactions.
* **Dynamic tools**: The tools and capabilities available from an integrated MCP server are defined by that external server and can change if the server's configuration is updated.

## Security and disclaimer

Integrating external MCP servers can expose your agents and data to third-party services. It is crucial to understand the security implications.

<Warning title="Important Disclaimer">
  By enabling MCP server integrations, you acknowledge that this may involve data sharing with
  third-party services not controlled by ElevenLabs. This could incur additional security risks.
  Please ensure you fully understand the implications, vet the security of any MCP server you
  integrate, and review our [MCP Integration Security
  Guidelines](/docs/agents-platform/customization/tools/mcp/security) before proceeding.
</Warning>

Refer to our [MCP Integration Security Guidelines](/docs/agents-platform/customization/tools/mcp/security) for detailed best practices.

## Finding or building MCP servers

* Utilize publicly available MCP servers from trusted providers
* Develop your own MCP server to expose your proprietary data or tools
* Explore the Model Context Protocol community and resources for examples and server implementations

### Resources

* [Anthropic's MCP server examples](https://docs.anthropic.com/en/docs/agents-and-tools/remote-mcp-servers#remote-mcp-server-examples) - A list of example servers by Anthropic
* [Awesome Remote MCP Servers](https://github.com/jaw9c/awesome-remote-mcp-servers) - A curated, open-source list of remote MCP servers
* [Remote MCP Server Directory](https://remote-mcp.com/) - A searchable list of Remote MCP servers


# MCP integration security

> Tips for securely integrating third-party Model Context Protocol servers with your ElevenLabs conversational agents.

<Error title="User Responsibility">
  You are responsible for the security, compliance, and behavior of any third-party MCP server you
  integrate with your ElevenLabs conversational agents. ElevenLabs provides the platform for
  integration but does not manage, endorse, or secure external MCP servers.
</Error>

## Overview

Integrating external servers via the Model Context Protocol (MCP) can greatly enhance your ElevenLabs conversational agents. However, this also means connecting to systems outside of ElevenLabs' direct control, which introduces important security considerations. As a user, you are responsible for the security and trustworthiness of any third-party MCP server you choose to integrate.

This guide outlines key security practices to consider when using MCP server integrations within ElevenLabs.

## Tool approval controls

ElevenLabs provides built-in security controls through tool approval modes that help you manage the security risks associated with MCP tool usage. These controls allow you to balance functionality with security based on your specific needs.

<Frame background="subtle">
  ![Tool approval mode settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9f4c208459131622478de5010e2234d3af8a03dc9bc5b7ec2fcab48a7be3bde3/assets/images/conversational-ai/mcp-approval.png)
</Frame>

### Approval mode options

* **Always Ask (Recommended)**: Provides maximum security by requiring explicit approval for every tool execution. This mode ensures you maintain full control over all MCP tool usage.
* **Fine-Grained Tool Approval**: Allows you to configure approval requirements on a per-tool basis, enabling automatic execution of trusted tools while requiring approval for sensitive operations.
* **No Approval**: Permits unrestricted tool usage without approval prompts. Only use this mode with thoroughly vetted and highly trusted MCP servers.

### Fine-grained security controls

Fine-Grained Tool Approval mode provides the most flexible security configuration, allowing you to classify each tool based on its risk profile:

<Frame background="subtle">
  ![Fine-grained tool approval
  settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/041cad753319ed92189ee8d4f70a9d3ed07177303bf71777ce36a90270a5dd24/assets/images/conversational-ai/mcp-finegrained-approvals.png)
</Frame>

* **Auto-approved tools**: Suitable for low-risk, read-only operations or tools you completely trust
* **Approval-required tools**: For tools that modify data, access sensitive information, or perform potentially risky operations
* **Disabled tools**: Completely block tools that are unnecessary or pose security risks

<Warning>
  Even with approval controls in place, carefully evaluate the trustworthiness of MCP servers and
  understand what each tool can access or modify before integration.
</Warning>

## Security tips

### 1. Vet your MCP servers

* **Trusted Sources**: Only integrate MCP servers from sources you trust and have verified. Understand who operates the server and their security posture.
* **Understand Capabilities**: Before integrating, thoroughly review the tools and data resources the MCP server exposes. Be aware of what actions its tools can perform (e.g., accessing files, calling external APIs, modifying data). The MCP `destructiveHint` and `readOnlyHint` annotations can provide clues but should not be solely relied upon for security decisions.
* **Review Server Security**: If possible, review the security practices of the MCP server provider. For MCP servers you develop, ensure you follow general server security best practices and the MCP-specific security guidelines.

### 2. Data sharing and privacy

* **Data Flow**: Be aware that when your agent uses an integrated MCP server, data from the conversation (which may include user inputs) will be sent to that external server.
* **Sensitive Information**: Exercise caution when allowing agents to send Personally Identifiable Information (PII) or other sensitive data to an MCP server. Ensure the server handles such data securely and in compliance with relevant privacy regulations.
* **Purpose Limitation**: Configure your agents and prompts to only share the necessary information with MCP server tools to perform their tasks.

### 3. Credential and connection security

* **Secure Storage**: If an MCP server requires API keys or other secrets for authentication, use any available secret management features within the ElevenLabs platform to store these credentials securely. Avoid hardcoding secrets.
* **HTTPS**: Ensure connections to MCP servers are made over HTTPS to encrypt data in transit.
* **Network Access**: If the MCP server is on a private network, ensure appropriate firewall rules and network ACLs are in place.

#### IP whitelisting

For additional security, you can whitelist the following static egress IPs from which ElevenLabs requests originate:

| Region       | IP Address     |
| ------------ | -------------- |
| US (Default) | 34.67.146.145  |
| US (Default) | 34.59.11.47    |
| EU           | 35.204.38.71   |
| EU           | 34.147.113.54  |
| Asia         | 35.185.187.110 |
| Asia         | 35.247.157.189 |

If you are using a [data residency region](/docs/overview/administration/data-residency) then the following IPs will be used:

| Region          | IP Address     |
| --------------- | -------------- |
| EU Residency    | 34.77.234.246  |
| EU Residency    | 34.140.184.144 |
| India Residency | 34.93.26.174   |
| India Residency | 34.93.252.69   |

If your infrastructure requires strict IP-based access controls, adding these IPs to your firewall allowlist will ensure you only receive requests from ElevenLabs' systems.

<Note>
  These static IPs are used across all ElevenLabs services including webhooks and MCP server
  requests, and will remain consistent.
</Note>

### 4. Understand code execution risks

* **Remote Execution**: Tools exposed by an MCP server execute code on that server. While this is the basis of their functionality, it's a critical security consideration. Malicious or poorly secured tools could pose a risk.
* **Input Validation**: Although the MCP server is responsible for validating inputs to its tools, be mindful of the data your agent might send. The LLM should be guided to use tools as intended.

### 5. Add guardrails

* **Prompt Injections**: Connecting to untrusted external MCP servers exposes the risk of prompt injection attacks. Ensure to add thorough guardrails to your system prompt to reduce the risk of exposure to a malicious attack.
* **Tool Approval Configuration**: Use the appropriate approval mode for your security requirements. Start with "Always Ask" for new integrations and only move to less restrictive modes after thorough testing and trust establishment.

### 6. Monitor and review

* **Logging (Server-Side)**: If you control the MCP server, implement comprehensive logging of tool invocations and data access.
* **Regular Review**: Periodically review your integrated MCP servers. Check if their security posture has changed or if new tools have been added that require re-assessment.
* **Approval Patterns**: Monitor tool approval requests to identify unusual patterns that might indicate security issues or misuse.

## Disclaimer

<Warning title="Important Disclaimer">
  By enabling MCP server integrations, you acknowledge that this may involve data sharing with
  third-party services not controlled by ElevenLabs. This could incur additional security risks.
  Please ensure you fully understand the implications, vet the security of any MCP server you
  integrate, and adhere to these security guidelines before proceeding.
</Warning>

For general information on the Model Context Protocol, refer to official MCP documentation and community resources.


# System tools

> Update the internal state of conversations without external requests.

**System tools** enable your assistant to update the internal state of a conversation. Unlike [server tools](/docs/agents-platform/customization/tools/server-tools) or [client tools](/docs/agents-platform/customization/tools/client-tools), system tools don't make external API calls or trigger client-side functions—they modify the internal state of the conversation without making external calls.

## Overview

Some applications require agents to control the flow or state of a conversation.
System tools provide this capability by allowing the assistant to perform actions related to the state of the call that don't require communicating with external servers or the client.

### Available system tools

<CardGroup cols={2}>
  <Card title="End call" icon="duotone square-phone-hangup" href="/docs/agents-platform/customization/tools/system-tools/end-call">
    Let your agent automatically terminate a conversation when appropriate conditions are met.
  </Card>

  <Card title="Language detection" icon="duotone earth-europe" href="/docs/agents-platform/customization/tools/system-tools/language-detection">
    Enable your agent to automatically switch to the user's language during conversations.
  </Card>

  <Card title="Agent transfer" icon="duotone arrow-right-arrow-left" href="/docs/agents-platform/customization/tools/system-tools/agent-transfer">
    Seamlessly transfer conversations between AI agents based on defined conditions.
  </Card>

  <Card title="Transfer to human" icon="duotone user-headset" href="/docs/agents-platform/customization/tools/system-tools/transfer-to-human">
    Seamlessly transfer the user to a human operator.
  </Card>

  <Card title="Skip turn" icon="duotone forward" href="/docs/agents-platform/customization/tools/system-tools/skip-turn">
    Enable the agent to skip their turns if the LLM detects the agent should not speak yet.
  </Card>

  <Card title="Play keypad touch tone" icon="duotone phone-office" href="/docs/agents-platform/customization/tools/system-tools/play-keypad-touch-tone">
    Enable agents to play DTMF tones to interact with automated phone systems and navigate menus.
  </Card>

  <Card title="Voicemail detection" icon="duotone voicemail" href="/docs/agents-platform/customization/tools/system-tools/voicemail-detection">
    Enable agents to automatically detect voicemail systems and optionally leave messages.
  </Card>
</CardGroup>

## Implementation

When creating an agent via API, you can add system tools to your agent configuration. Here's how to implement both the end call and language detection tools:

## Custom LLM integration

When using a custom LLM with ElevenLabs agents, system tools are exposed as function definitions that your LLM can call. Each system tool has specific parameters and trigger conditions:

### Available system tools

<AccordionGroup>
  <Accordion title="End call">
    **Purpose**: Automatically terminate conversations when appropriate conditions are met.

    **Trigger conditions**: The LLM should call this tool when:

    * The main task has been completed and user is satisfied
    * The conversation reached natural conclusion with mutual agreement
    * The user explicitly indicates they want to end the conversation

    **Parameters**:

    * `reason` (string, required): The reason for ending the call
    * `message` (string, optional): A farewell message to send to the user before ending the call

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "end_call",
        "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
      }
    }
    ```

    **Implementation**: Configure as a system tool in your agent settings. The LLM will receive detailed instructions about when to call this function.

    Learn more: [End call tool](/docs/agents-platform/customization/tools/system-tools/end-call)
  </Accordion>

  <Accordion title="Language detection">
    **Purpose**: Automatically switch to the user's detected language during conversations.

    **Trigger conditions**: The LLM should call this tool when:

    * User speaks in a different language than the current conversation language
    * User explicitly requests to switch languages
    * Multi-language support is needed for the conversation

    **Parameters**:

    * `reason` (string, required): The reason for the language switch
    * `language` (string, required): The language code to switch to (must be in supported languages list)

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "language_detection",
        "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
      }
    }
    ```

    **Implementation**: Configure supported languages in agent settings and add the language detection system tool. The agent will automatically switch voice and responses to match detected languages.

    Learn more: [Language detection tool](/docs/agents-platform/customization/tools/system-tools/language-detection)
  </Accordion>

  <Accordion title="Agent transfer">
    **Purpose**: Transfer conversations between specialized AI agents based on user needs.

    **Trigger conditions**: The LLM should call this tool when:

    * User request requires specialized knowledge or different agent capabilities
    * Current agent cannot adequately handle the query
    * Conversation flow indicates need for different agent type

    **Parameters**:

    * `reason` (string, optional): The reason for the agent transfer
    * `agent_number` (integer, required): Zero-indexed number of the agent to transfer to (based on configured transfer rules)

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "transfer_to_agent",
        "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
      }
    }
    ```

    **Implementation**: Define transfer rules mapping conditions to specific agent IDs. Configure which agents the current agent can transfer to. Agents are referenced by zero-indexed numbers in the transfer configuration.

    Learn more: [Agent transfer tool](/docs/agents-platform/customization/tools/system-tools/agent-transfer)
  </Accordion>

  <Accordion title="Transfer to human">
    **Purpose**: Seamlessly hand off conversations to human operators when AI assistance is insufficient.

    **Trigger conditions**: The LLM should call this tool when:

    * Complex issues requiring human judgment
    * User explicitly requests human assistance
    * AI reaches limits of capability for the specific request
    * Escalation protocols are triggered

    **Parameters**:

    * `reason` (string, optional): The reason for the transfer
    * `transfer_number` (string, required): The phone number to transfer to (must match configured numbers)
    * `client_message` (string, required): Message read to the client while waiting for transfer
    * `agent_message` (string, required): Message for the human operator receiving the call

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "transfer_to_number",
        "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
      }
    }
    ```

    **Implementation**: Configure transfer phone numbers and conditions. Define messages for both customer and receiving human operator. Works with both Twilio and SIP trunking.

    Learn more: [Transfer to human tool](/docs/agents-platform/customization/tools/system-tools/transfer-to-human)
  </Accordion>

  <Accordion title="Skip turn">
    **Purpose**: Allow the agent to pause and wait for user input without speaking.

    **Trigger conditions**: The LLM should call this tool when:

    * User indicates they need a moment ("Give me a second", "Let me think")
    * User requests pause in conversation flow
    * Agent detects user needs time to process information

    **Parameters**:

    * `reason` (string, optional): Free-form reason explaining why the pause is needed

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "skip_turn",
        "arguments": "{\"reason\": \"User requested time to think\"}"
      }
    }
    ```

    **Implementation**: No additional configuration needed. The tool simply signals the agent to remain silent until the user speaks again.

    Learn more: [Skip turn tool](/docs/agents-platform/customization/tools/system-tools/skip-turn)
  </Accordion>

  <Accordion title="Play keypad touch tone">
    **Parameters**:

    * `reason` (string, optional): The reason for playing the DTMF tones (e.g., "navigating to extension", "entering PIN")
    * `dtmf_tones` (string, required): The DTMF sequence to play. Valid characters: 0-9, \*, #, w (0.5s pause), W (1s pause)

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "play_keypad_touch_tone",
        "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
      }
    }
    ```

    Learn more: [Play keypad touch tone tool](/docs/agents-platform/customization/tools/system-tools/play-keypad-touch-tone)
  </Accordion>

  <Accordion title="Voicemail detection">
    **Parameters**:

    * `reason` (string, required): The reason for detecting voicemail (e.g., "automated greeting detected", "no human response")

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "voicemail_detection",
        "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
      }
    }
    ```

    Learn more: [Voicemail detection tool](/docs/agents-platform/customization/tools/system-tools/voicemail-detection)
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System,
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create system tools
  end_call_tool = PromptAgentInputToolsItem_System(
      name="end_call",
      description=""  # Optional: Customize when the tool should be triggered
  )

  language_detection_tool = PromptAgentInputToolsItem_System(
      name="language_detection",
      description=""  # Optional: Customize when the tool should be triggered
  )

  # Create the agent configuration with both tools
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              tools=[end_call_tool, language_detection_tool]
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with system tools
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          tools: [
            {
              type: 'system',
              name: 'end_call',
              description: '',
            },
            {
              type: 'system',
              name: 'language_detection',
              description: '',
            },
          ],
        },
      },
    },
  });
  ```
</CodeGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can system tools be combined with other tool types?">
    Yes, system tools can be used alongside server tools and client tools in the same assistant.
    This allows for comprehensive functionality that combines internal state management with
    external interactions.
  </Accordion>
</AccordionGroup>

```
```


# End call

> Let your agent automatically hang up on the user.

<Warning>
  The **End Call** tool is added to agents created in the ElevenLabs dashboard by default. For
  agents created via API or SDK, if you would like to enable the End Call tool, you must add it
  manually as a system tool in your agent configuration. [See API Implementation
  below](#api-implementation) for details.
</Warning>

<Frame background="subtle">
  ![End call](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f260bfd4e43f7fb0374ce12d2ed984efb946a8ca9ebaa1c2d4b3e6d5f52a7851/assets/images/conversational-ai/end-call-tool.png)
</Frame>

## Overview

The **End Call** tool allows your conversational agent to terminate a call with the user. This is a system tool that provides flexibility in how and when calls are ended.

## Functionality

* **Default behavior**: The tool can operate without any user-defined prompts, ending the call when the conversation naturally concludes.
* **Custom prompts**: Users can specify conditions under which the call should end. For example:
  * End the call if the user says "goodbye."
  * Conclude the call when a specific task is completed.

**Purpose**: Automatically terminate conversations when appropriate conditions are met.

**Trigger conditions**: The LLM should call this tool when:

* The main task has been completed and user is satisfied
* The conversation reached natural conclusion with mutual agreement
* The user explicitly indicates they want to end the conversation

**Parameters**:

* `reason` (string, required): The reason for ending the call
* `message` (string, optional): A farewell message to send to the user before ending the call

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "end_call",
    "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
  }
}
```

**Implementation**: Configure as a system tool in your agent settings. The LLM will receive detailed instructions about when to call this function.

### API Implementation

When creating an agent via API, you can add the End Call tool to your agent configuration. It should be defined as a system tool:

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create the end call tool
  end_call_tool = PromptAgentInputToolsItem_System(
      name="end_call",
      description=""  # Optional: Customize when the tool should be triggered
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              tools=[end_call_tool]
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with end call tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          tools: [
            {
              type: 'system',
              name: 'end_call',
              description: '', // Optional: Customize when the tool should be triggered
            },
          ],
        },
      },
    },
  });
  ```

  ```bash
  curl -X POST https://api.elevenlabs.io/v1/convai/agents/create \
       -H "xi-api-key: YOUR_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
    "conversation_config": {
      "agent": {
        "prompt": {
          "tools": [
            {
              "type": "system",
              "name": "end_call",
              "description": ""
            }
          ]
        }
      }
    }
  }'
  ```
</CodeBlocks>

<Tip>
  Leave the description blank to use the default end call prompt.
</Tip>

## Example prompts

**Example 1: Basic End Call**

```
End the call when the user says goodbye, thank you, or indicates they have no more questions.
```

**Example 2: End Call with Custom Prompt**

```
End the call when the user says goodbye, thank you, or indicates they have no more questions. You can only end the call after all their questions have been answered. Please end the call only after confirming that the user doesn't need any additional assistance.
```


# Language detection

> Let your agent automatically switch to the language

## Overview

The `language detection` system tool allows your ElevenLabs agent to switch its output language to any the agent supports.
This system tool is not enabled automatically. Its description can be customized to accommodate your specific use case.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/YhF2gKv9ozc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Note>
  Where possible, we recommend enabling all languages for an agent and enabling the language
  detection system tool.
</Note>

Our language detection tool triggers language switching in two cases, both based on the received audio's detected language and content:

* `detection` if a user speaks a different language than the current output language, a switch will be triggered
* `content` if the user asks in the current language to change to a new language, a switch will be triggered

**Purpose**: Automatically switch to the user's detected language during conversations.

**Trigger conditions**: The LLM should call this tool when:

* User speaks in a different language than the current conversation language
* User explicitly requests to switch languages
* Multi-language support is needed for the conversation

**Parameters**:

* `reason` (string, required): The reason for the language switch
* `language` (string, required): The language code to switch to (must be in supported languages list)

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "language_detection",
    "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
  }
}
```

**Implementation**: Configure supported languages in agent settings and add the language detection system tool. The agent will automatically switch voice and responses to match detected languages.

## Enabling language detection

<Steps>
  <Step title="Configure supported languages">
    The languages that the agent can switch to must be defined in the `Agent` settings tab.

    <Frame background="subtle">
      ![Agent languages](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/633707d54276febd3baa054c4f41b186225b74f606307a46e8262607befc8381/assets/images/conversational-ai/agent-languages.png)
    </Frame>
  </Step>

  <Step title="Add the language detection tool">
    Enable language detection by selecting the pre-configured system tool to your agent's tools in the `Agent` tab.
    This is automatically available as an option when selecting `add tool`.

    <Frame background="subtle">
      ![System tool](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3d17048ab2bc1a0547c49056abb98f624caf866927ff1714af27f898b06ab18f/assets/images/conversational-ai/language-detection-preconfig.png)
    </Frame>
  </Step>

  <Step title="Configure tool description">
    Add a description that specifies when to call the tool

    <Frame background="subtle">
      ![Description](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3bebc9fe07dba7121bce7793f3793858c710fc8ea1c221347604eb05929271df/assets/images/conversational-ai/language_detection.png)
    </Frame>
  </Step>
</Steps>

### API Implementation

When creating an agent via API, you can add the `language detection` tool to your agent configuration. It should be defined as a system tool:

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System,
      LanguagePresetInput,
      ConversationConfigClientOverrideInput,
      AgentConfigOverride,
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create the language detection tool
  language_detection_tool = PromptAgentInputToolsItem_System(
      name="language_detection",
      description=""  # Optional: Customize when the tool should be triggered
  )

  # Create language presets
  language_presets = {
      "nl": LanguagePresetInput(
          overrides=ConversationConfigClientOverrideInput(
              agent=AgentConfigOverride(
                  prompt=None,
                  first_message="Hoi, hoe gaat het met je?",
                  language=None
              ),
              tts=None
          ),
          first_message_translation=None
      ),
      "fi": LanguagePresetInput(
          overrides=ConversationConfigClientOverrideInput(
              agent=AgentConfigOverride(
                  first_message="Hei, kuinka voit?",
              ),
              tts=None
          ),
      ),
      "tr": LanguagePresetInput(
          overrides=ConversationConfigClientOverrideInput(
              agent=AgentConfigOverride(
                  prompt=None,
                  first_message="Merhaba, nasılsın?",
                  language=None
              ),
              tts=None
          ),
      ),
      "ru": LanguagePresetInput(
          overrides=ConversationConfigClientOverrideInput(
              agent=AgentConfigOverride(
                  prompt=None,
                  first_message="Привет, как ты?",
                  language=None
              ),
              tts=None
          ),
      ),
      "pt": LanguagePresetInput(
          overrides=ConversationConfigClientOverrideInput(
              agent=AgentConfigOverride(
                  prompt=None,
                  first_message="Oi, como você está?",
                  language=None
              ),
              tts=None
          ),
      )
  }

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              tools=[language_detection_tool],
              first_message="Hi how are you?"
          )
      ),
      language_presets=language_presets
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with language detection tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          tools: [
            {
              type: 'system',
              name: 'language_detection',
              description: '', // Optional: Customize when the tool should be triggered
            },
          ],
          firstMessage: 'Hi, how are you?',
        },
      },
      languagePresets: {
        nl: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'Hoi, hoe gaat het met je?',
              language: null,
            },
            tts: null,
          },
        },
        fi: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'Hei, kuinka voit?',
              language: null,
            },
            tts: null,
          },
          firstMessageTranslation: {
            sourceHash: '{"firstMessage":"Hi how are you?","language":"en"}',
            text: 'Hei, kuinka voit?',
          },
        },
        tr: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'Merhaba, nasılsın?',
              language: null,
            },
            tts: null,
          },
        },
        ru: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'Привет, как ты?',
              language: null,
            },
            tts: null,
          },
        },
        pt: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'Oi, como você está?',
              language: null,
            },
            tts: null,
          },
        },
        ar: {
          overrides: {
            agent: {
              prompt: null,
              firstMessage: 'مرحبًا كيف حالك؟',
              language: null,
            },
            tts: null,
          },
        },
      },
    },
  });
  ```

  ```bash
  curl -X POST https://api.elevenlabs.io/v1/convai/agents/create \
       -H "xi-api-key: YOUR_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
    "conversation_config": {
      "agent": {
        "prompt": {
          "first_message": "Hi how are you?",
          "tools": [
            {
              "type": "system",
              "name": "language_detection",
              "description": ""
            }
          ]
        }
      },
      "language_presets": {
        "nl": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "Hoi, hoe gaat het met je?",
              "language": null
            },
            "tts": null
          }
        },
        "fi": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "Hei, kuinka voit?",
              "language": null
            },
            "tts": null
          }
        },
        "tr": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "Merhaba, nasılsın?",
              "language": null
            },
            "tts": null
          }
        },
        "ru": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "Привет, как ты?",
              "language": null
            },
            "tts": null
          }
        },
        "pt": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "Oi, como você está?",
              "language": null
            },
            "tts": null
          }
        },
        "ar": {
          "overrides": {
            "agent": {
              "prompt": null,
              "first_message": "مرحبًا كيف حالك؟",
              "language": null
            },
            "tts": null
          }
        }
      }
    }
  }'
  ```
</CodeBlocks>

<Tip>
  Leave the description blank to use the default language detection prompt.
</Tip>


# Agent transfer

> Seamlessly transfer the user between ElevenLabs agents based on defined conditions.

## Overview

Agent-agent transfer allows a ElevenLabs agent to hand off the ongoing conversation to another designated agent when specific conditions are met. This enables the creation of sophisticated, multi-layered conversational workflows where different agents handle specific tasks or levels of complexity.

For example, an initial agent (Orchestrator) could handle general inquiries and then transfer the call to a specialized agent based on the conversation's context. Transfers can also be nested:

<Frame background="subtle" caption="Example Agent Transfer Hierarchy">
  ```text
  Orchestrator Agent (Initial Qualification)
  │
  ├───> Agent 1 (e.g., Availability Inquiries)
  │
  ├───> Agent 2 (e.g., Technical Support)
  │     │
  │     └───> Agent 2a (e.g., Hardware Support)
  │
  └───> Agent 3 (e.g., Billing Issues)

  ```
</Frame>

<Note>
  We recommend using the `gpt-4o` or `gpt-4o-mini` models when using agent-agent transfers due to better tool calling.
</Note>

**Purpose**: Transfer conversations between specialized AI agents based on user needs.

**Trigger conditions**: The LLM should call this tool when:

* User request requires specialized knowledge or different agent capabilities
* Current agent cannot adequately handle the query
* Conversation flow indicates need for different agent type

**Parameters**:

* `reason` (string, optional): The reason for the agent transfer
* `agent_number` (integer, required): Zero-indexed number of the agent to transfer to (based on configured transfer rules)

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "transfer_to_agent",
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
  }
}
```

**Implementation**: Define transfer rules mapping conditions to specific agent IDs. Configure which agents the current agent can transfer to. Agents are referenced by zero-indexed numbers in the transfer configuration.

## Enabling agent transfer

Agent transfer is configured using the `transfer_to_agent` system tool.

<Steps>
  <Step title="Add the transfer tool">
    Enable agent transfer by selecting the `transfer_to_agent` system tool in your agent's configuration within the `Agent` tab. Choose "Transfer to AI Agent" when adding a tool.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3e2756669b192395680d48a17c622493faee9fb61649f491bbe66820a91d46ef/assets/images/conversational-ai/transfertool.png" alt="Add Transfer Tool" />
    </Frame>
  </Step>

  <Step title="Configure tool description (optional)">
    You can provide a custom description to guide the LLM on when to trigger a transfer. If left blank, a default description encompassing the defined transfer rules will be used.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b916200ef66cd0c6f5af7f6ba51b4b48eb1a266c7b10e863ae874c5a11452ae/assets/images/conversational-ai/transferconfig.png" alt="Transfer Tool Description" />
    </Frame>
  </Step>

  <Step title="Define transfer rules">
    Configure the specific rules for transferring to other agents. For each rule, specify:

    * **Agent**: The target agent to transfer the conversation to.
    * **Condition**: A natural language description of the circumstances under which the transfer should occur (e.g., "User asks about billing details", "User requests technical support for product X").
    * **Delay before transfer (milliseconds)**: The minimum delay (in milliseconds) before the transfer occurs. Defaults to 0 for immediate transfer.
    * **Transfer Message**: An optional custom message to play during the transfer. If left blank, the transfer will occur silently.
    * **Enable First Message**: Whether the transferred agent should play its first message after the transfer. Defaults to off.

    The LLM will use these conditions, along with the tool description, to decide when and to which agent (by number) to transfer.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b1b7e0f58ae757640af46630fde962a78ef4a164a380f974297bb643ccc29443/assets/images/conversational-ai/transferrule.png" alt="Transfer Rules Configuration" />
    </Frame>

    <Note>
      Ensure that the user account creating the agent has at least viewer permissions for any target agents specified in the transfer rules.
    </Note>
  </Step>
</Steps>

## API Implementation

You can configure the `transfer_to_agent` system tool when creating or updating an agent via the API.

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System,
      SystemToolConfigInputParams_TransferToAgent,
      AgentTransfer
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Define transfer rules with new options
  transfer_rules = [
      AgentTransfer(
          agent_id="AGENT_ID_1",
          condition="When the user asks for billing support.",
          delay_ms=1000,  # 1 second delay
          transfer_message="I'm connecting you to our billing specialist.",
          enable_transferred_agent_first_message=True
      ),
      AgentTransfer(
          agent_id="AGENT_ID_2",
          condition="When the user requests advanced technical help.",
          delay_ms=0,  # Immediate transfer
          transfer_message=None,  # Silent transfer
          enable_transferred_agent_first_message=False
      )
  ]

  # Create the transfer tool configuration
  transfer_tool = PromptAgentInputToolsItem_System(
      type="system",
      name="transfer_to_agent",
      description="Transfer the user to a specialized agent based on their request.", # Optional custom description
      params=SystemToolConfigInputParams_TransferToAgent(
          transfers=transfer_rules
      )
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              prompt="You are a helpful assistant.",
              first_message="Hi, how can I help you today?",
              tools=[transfer_tool],
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )

  print(response)
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Define transfer rules with new options
  const transferRules = [
    {
      agentId: 'AGENT_ID_1',
      condition: 'When the user asks for billing support.',
      delayMs: 1000, // 1 second delay
      transferMessage: "I'm connecting you to our billing specialist.",
      enableTransferredAgentFirstMessage: true,
    },
    {
      agentId: 'AGENT_ID_2',
      condition: 'When the user requests advanced technical help.',
      delayMs: 0, // Immediate transfer
      transferMessage: null, // Silent transfer
      enableTransferredAgentFirstMessage: false,
    },
  ];

  // Create the agent with the transfer tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          prompt: 'You are a helpful assistant.',
          firstMessage: 'Hi, how can I help you today?',
          tools: [
            {
              type: 'system',
              name: 'transfer_to_agent',
              description: 'Transfer the user to a specialized agent based on their request.', // Optional custom description
              params: {
                systemToolType: 'transfer_to_agent',
                transfers: transferRules,
              },
            },
          ],
        },
      },
    },
  });
  ```
</CodeBlocks>


# Transfer to human

> Seamlessly transfer the user to a human operator via phone number based on defined conditions.

## Overview

Human transfer allows a ElevenLabs agent to transfer the ongoing call to a specified phone number or SIP URI when certain conditions are met. This enables agents to hand off complex issues, specific requests, or situations requiring human intervention to a live operator.

This feature utilizes the `transfer_to_number` system tool which supports transfers via Twilio and SIP trunk numbers. When triggered, the agent can provide a message to the user while they wait and a separate message summarizing the situation for the human operator receiving the call.

<Note>
  The `transfer_to_number` system tool is only available for phone calls and is not available in the
  chat widget.
</Note>

## Transfer Types

The system supports two types of transfers:

* **Conference Transfer**: Default behavior that calls the destination and adds the participant to a conference room, then removes the AI agent so only the caller and transferred participant remain.
* **SIP REFER Transfer**: Uses the SIP REFER protocol to transfer calls directly to the destination. Works with both phone numbers and SIP URIs, but only available when using SIP protocol during the conversation and requires your SIP Trunk to allow transfer via SIP REFER.

**Purpose**: Seamlessly hand off conversations to human operators when AI assistance is insufficient.

**Trigger conditions**: The LLM should call this tool when:

* Complex issues requiring human judgment
* User explicitly requests human assistance
* AI reaches limits of capability for the specific request
* Escalation protocols are triggered

**Parameters**:

* `reason` (string, optional): The reason for the transfer
* `transfer_number` (string, required): The phone number to transfer to (must match configured numbers)
* `client_message` (string, required): Message read to the client while waiting for transfer
* `agent_message` (string, required): Message for the human operator receiving the call

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}
```

**Implementation**: Configure transfer phone numbers and conditions. Define messages for both customer and receiving human operator. Works with both Twilio and SIP trunking.

## Numbers that can be transferred to

Human transfer supports transferring to external phone numbers using both [SIP trunking](/docs/agents-platform/phone-numbers/sip-trunking) and [Twilio phone numbers](/docs/agents-platform/phone-numbers/twilio-integration/native-integration).

## Enabling human transfer

Human transfer is configured using the `transfer_to_number` system tool.

<Steps>
  <Step title="Add the transfer tool">
    Enable human transfer by selecting the `transfer_to_number` system tool in your agent's configuration within the `Agent` tab. Choose "Transfer to Human" when adding a tool.

    <Frame background="subtle" caption="Select 'Transfer to Human' tool">
      {/* Placeholder for image showing adding the 'Transfer to Human' tool */}

      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1b0a0985dd32cab9532b38b80aaa90873b4076bb26e7a47ce2e12832dd78ea45/assets/images/conversational-ai/transfer_human.png" alt="Add Human Transfer Tool" />
    </Frame>
  </Step>

  <Step title="Configure tool description (optional)">
    You can provide a custom description to guide the LLM on when to trigger a transfer. If left blank, a default description encompassing the defined transfer rules will be used.

    <Frame background="subtle" caption="Configure transfer tool description">
      {/* Placeholder for image showing the tool description field */}

      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/23b446030f915db9a10693153e44f95ab59c313e01df2b95291e40e12f2f4bde/assets/images/conversational-ai/transfer_human_tool.png" alt="Human Transfer Tool Description" />
    </Frame>
  </Step>

  <Step title="Define transfer rules">
    Configure the specific rules for transferring to phone numbers or SIP URIs. For each rule, specify:

    * **Transfer Type**: Choose between Conference (default) or SIP REFER transfer methods
    * **Number Type**: Select Phone for regular phone numbers or SIP URI for SIP addresses
    * **Phone Number/SIP URI**: The target destination in the appropriate format:
      * Phone numbers: E.164 format (e.g., +12125551234)
      * SIP URIs: SIP format (e.g., sip:[1234567890@example.com](mailto:1234567890@example.com))
    * **Condition**: A natural language description of the circumstances under which the transfer should occur (e.g., "User explicitly requests to speak to a human", "User needs to update sensitive account information").

    The LLM will use these conditions, along with the tool description, to decide when and to which destination to transfer.

    <Note>
      **SIP REFER transfers** require SIP protocol during the conversation and your SIP Trunk must allow transfer via SIP REFER. Only SIP REFER supports transferring to a SIP URI.
    </Note>

    <Frame background="subtle" caption="Define transfer rules with phone number and condition">
      {/* Placeholder for image showing transfer rules configuration */}

      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/86e46148dc133fe68e6b517752d38bf493bef8347fee91a577e9f27600bafa5d/assets/images/conversational-ai/transfer_human_rule.png" alt="Human Transfer Rules Configuration" />
    </Frame>

    <Note>
      Ensure destinations are correctly formatted:

      * Phone numbers: E.164 format and associated with a properly configured account
      * SIP URIs: Valid SIP format (sip:user\@domain or sips:user\@domain)
    </Note>
  </Step>

  <Step title="Configure custom SIP REFER headers (optional)">
    When using SIP REFER transfers, you can include custom SIP headers to pass additional information to the receiving system.

    For each custom header, specify:

    * **Header Name**: The SIP header name (e.g., `X-Customer-ID`, `X-Priority`)
    * **Header Value**: The header value, which can be static text or include [dynamic variables](/docs/agents-platform/customization/dynamic-variables)

    <Note>
      Custom SIP REFER headers are only included with **SIP REFER transfers**. Conference transfers do not support custom headers.
    </Note>

    <Warning>
      System headers `X-Conversation-ID` and `X-Caller-ID` are automatically included by ElevenLabs and will override any custom headers with the same names (case-insensitive).
    </Warning>
  </Step>
</Steps>

## API Implementation

You can configure the `transfer_to_number` system tool when creating or updating an agent via the API. The tool allows specifying messages for both the client (user being transferred) and the agent (human operator receiving the call).

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System,
      SystemToolConfigInputParams_TransferToNumber,
      PhoneNumberTransfer,
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Define transfer rules
  transfer_rules = [
      PhoneNumberTransfer(
          transfer_destination={"type": "phone", "phone_number": "+15551234567"},
          condition="When the user asks for billing support.",
          transfer_type="conference"
      ),
      PhoneNumberTransfer(
          transfer_destination={"type": "sip_uri", "sip_uri": "sip:support@example.com"},
          condition="When the user requests to file a formal complaint.",
          transfer_type="sip_refer",
          custom_sip_headers=[
              {"key": "X-Department", "value": "complaints"},
              {"key": "X-Priority", "value": "high"},
              {"key": "X-Customer-ID", "value": "{{customer_id}}"}
          ]
      )
  ]

  # Create the transfer tool configuration
  transfer_tool = PromptAgentInputToolsItem_System(
      type="system",
      name="transfer_to_human",
      description="Transfer the user to a specialized agent based on their request.", # Optional custom description
      params=SystemToolConfigInputParams_TransferToNumber(
          transfers=transfer_rules
      )
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              prompt="You are a helpful assistant.",
              first_message="Hi, how can I help you today?",
              tools=[transfer_tool],
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )

  # Note: When the LLM decides to call this tool, it needs to provide:
  # - transfer_number: The phone number to transfer to (must match one defined in rules).
  # - client_message: Message read to the user during transfer.
  # - agent_message: Message read to the human operator receiving the call.
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Define transfer rules
  const transferRules = [
    {
      transferDestination: { type: 'phone', phoneNumber: '+15551234567' },
      condition: 'When the user asks for billing support.',
      transferType: 'conference',
    },
    {
      transferDestination: { type: 'sip_uri', sipUri: 'sip:support@example.com' },
      condition: 'When the user requests to file a formal complaint.',
      transferType: 'sip_refer',
      customSipHeaders: [
        { key: 'X-Department', value: 'complaints' },
        { key: 'X-Priority', value: 'high' },
        { key: 'X-Customer-ID', value: '{{customer_id}}' },
      ],
    },
  ];

  // Create the agent with the transfer tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          prompt: 'You are a helpful assistant.',
          firstMessage: 'Hi, how can I help you today?',
          tools: [
            {
              type: 'system',
              name: 'transfer_to_number',
              description: 'Transfer the user to a human operator based on their request.', // Optional custom description
              params: {
                systemToolType: 'transfer_to_number',
                transfers: transferRules,
              },
            },
          ],
        },
      },
    },
  });

  // Note: When the LLM decides to call this tool, it needs to provide:
  // - transfer_number: The phone number to transfer to (must match one defined in rules).
  // - client_message: Message read to the user during transfer.
  // - agent_message: Message read to the human operator receiving the call.
  </code_block_to_apply_changes_from>
  ```
</CodeBlocks>


# Skip turn

> Allow your agent to pause and wait for the user to speak next.

## Overview

The **Skip Turn** tool allows your conversational agent to explicitly pause and wait for the user to speak or act before continuing. This system tool is useful when the user indicates they need a moment, for example, by saying "Give me a second," "Let me think," or "One moment please."

## Functionality

* **User-Initiated Pause**: The tool is designed to be invoked by the LLM when it detects that the user needs a brief pause without interruption.
* **No Verbal Response**: After this tool is called, the assistant will not speak. It waits for the user to re-engage or for another turn-taking condition to be met.
* **Seamless Conversation Flow**: It helps maintain a natural conversational rhythm by respecting the user's need for a short break without ending the interaction or the agent speaking unnecessarily.

**Purpose**: Allow the agent to pause and wait for user input without speaking.

**Trigger conditions**: The LLM should call this tool when:

* User indicates they need a moment ("Give me a second", "Let me think")
* User requests pause in conversation flow
* Agent detects user needs time to process information

**Parameters**:

* `reason` (string, optional): Free-form reason explaining why the pause is needed

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "skip_turn",
    "arguments": "{\"reason\": \"User requested time to think\"}"
  }
}
```

**Implementation**: No additional configuration needed. The tool simply signals the agent to remain silent until the user speaks again.

### API implementation

When creating an agent via API, you can add the Skip Turn tool to your agent configuration. It should be defined as a system tool, with the name `skip_turn`.

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create the skip turn tool
  skip_turn_tool = PromptAgentInputToolsItem_System(
      name="skip_turn",
      description=""  # Optional: Customize when the tool should be triggered, or leave blank for default.
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              tools=[skip_turn_tool]
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with skip turn tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          tools: [
            {
              type: 'system',
              name: 'skip_turn',
              description: '', // Optional: Customize when the tool should be triggered, or leave blank for default.
            },
          ],
        },
      },
    },
  });
  ```
</CodeBlocks>

## UI configuration

You can also configure the Skip Turn tool directly within the Agent's UI, in the tools section.

<Steps>
  ### Step 1: Add a new tool

  Navigate to your agent's configuration page. In the "Tools" section, click on "Add tool", the `Skip Turn` option will already be available.

  <Frame background="subtle">
    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8b95051da94ada3dae7e42121148ad4509b49413e73bd16351142372ca26a68d/assets/images/conversational-ai/skip-turn-option.png" alt="Add Skip Turn Tool Option" />
  </Frame>

  ### Step 2: Configure the tool

  You can optionally provide a description to customize when the LLM should trigger this tool, or leave it blank to use the default behavior.

  <Frame background="subtle">
    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cbb419db630beb4feefc390ef3f3576f7a6dc2df098faec4fbd2d1d5e703364f/assets/images/conversational-ai/skip-turn-config.png" alt="Configure Skip Turn Tool" />
  </Frame>

  ### Step 3: Enable the tool

  Once configured, the `Skip Turn` tool will appear in your agent's list of enabled tools and the agent will be able to skip turns. .

  <Frame background="subtle">
    <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/bdb738dc85ff91107cafa5899aad116420aabe9fe794b648bc1f0751729ba5af/assets/images/conversational-ai/skip-turn-enabled.png" alt="Skip Turn Tool Enabled" />
  </Frame>
</Steps>


# Play keypad touch tone

> Enable agents to play DTMF tones to interact with automated phone systems and navigate menus.

## Overview

The keypad touch tone tool allows ElevenLabs agents to play DTMF (Dual-Tone Multi-Frequency) tones during phone calls; these are the tones that are played when you press numbers on your keypad. This enables agents to interact with automated phone systems, navigate voice menus, enter extensions, input PIN codes, and perform other touch-tone operations that would typically require a human caller to press keys on their phone keypad.

This system tool supports standard DTMF tones (0-9, \*, #) as well as pause commands for timing control. It works seamlessly with both Twilio and SIP trunking phone integrations, automatically generating the appropriate audio tones for the underlying telephony infrastructure.

## Functionality

* **Standard DTMF tones**: Supports all standard keypad characters (0-9, \*, #)
* **Pause control**: Includes pause commands for precise timing (w = 0.5s, W = 1.0s)
* **Multi-provider support**: Works with both Twilio and SIP trunking integrations

This system tool can be used to navigate phone menus, enter extensions and input codes.
The LLM determines when and what tones to play based on conversation context.

The default tool description explains to the LLM powering the conversation that it has access to play these tones,
and we recommend updating your agent's system prompt to explain when the agent should call this tool.

**Parameters**:

* `reason` (string, optional): The reason for playing the DTMF tones (e.g., "navigating to extension", "entering PIN")
* `dtmf_tones` (string, required): The DTMF sequence to play. Valid characters: 0-9, \*, #, w (0.5s pause), W (1s pause)

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "play_keypad_touch_tone",
    "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
  }
}
```

## Supported characters

The tool supports the following DTMF characters and commands:

* **Digits**: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
* **Special tones**: `*` (star), `#` (pound/hash)
* **Pause commands**:
  * `w` - Short pause (0.5 seconds)
  * `W` - Long pause (1.0 second)

## API Implementation

You can configure the `play_keypad_touch_tone` system tool when creating or updating an agent via the API. This tool requires no additional configuration parameters beyond enabling it.

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System,
      SystemToolConfigInputParams_PlayKeypadTouchTone,
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create the keypad touch tone tool configuration
  keypad_tool = PromptAgentInputToolsItem_System(
      type="system",
      name="play_keypad_touch_tone",
      description="Play DTMF tones to interact with automated phone systems.", # Optional custom description
      params=SystemToolConfigInputParams_PlayKeypadTouchTone(
          system_tool_type="play_keypad_touch_tone"
      )
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              prompt="You are a helpful assistant that can interact with phone systems.",
              first_message="Hi, I can help you navigate phone systems. How can I assist you today?",
              tools=[keypad_tool],
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with the keypad touch tone tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          prompt: 'You are a helpful assistant that can interact with phone systems.',
          firstMessage: 'Hi, I can help you navigate phone systems. How can I assist you today?',
          tools: [
            {
              type: 'system',
              name: 'play_keypad_touch_tone',
              description: 'Play DTMF tones to interact with automated phone systems.', // Optional custom description
              params: {
                systemToolType: 'play_keypad_touch_tone',
              },
            },
          ],
        },
      },
    },
  });
  ```
</CodeBlocks>

<Note>
  The tool only works during active phone calls powered by Twilio or SIP trunking. It will return an
  error if called outside of a phone conversation context.
</Note>


# Voicemail detection

> Enable agents to automatically detect voicemail systems and optionally leave messages.

## Overview

The **Voicemail Detection** tool allows your ElevenLabs agent to automatically identify when a call has been answered by a voicemail system rather than a human. This system tool enables agents to handle automated voicemail scenarios gracefully by either leaving a pre-configured message or ending the call immediately.

## Functionality

* **Automatic Detection**: The LLM analyzes conversation patterns to identify voicemail systems based on automated greetings and prompts
* **Configurable Response**: Choose to either leave a custom voicemail message or end the call immediately when voicemail is detected
* **Call Termination**: After detection and optional message delivery, the call is automatically terminated
* **Status Tracking**: Voicemail detection events are logged and can be viewed in conversation history and batch call results

**Parameters**:

* `reason` (string, required): The reason for detecting voicemail (e.g., "automated greeting detected", "no human response")

**Function call format**:

```json
{
  "type": "function",
  "function": {
    "name": "voicemail_detection",
    "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
  }
}
```

## Configuration Options

The voicemail detection tool can be configured with the following options:

<Frame background="subtle">
  ![Voicemail detection configuration
  interface](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f2f9a87e27ce0d5f631d2d294163e8df39e6dee5b3a98aaba692589c66364550/assets/images/conversational-ai/voicemail_detection.png)
</Frame>

* **Voicemail Message**: You can configure an optional custom message to be played when voicemail is detected. This message supports [dynamic variables](/docs/agents-platform/customization/personalization/dynamic-variables), allowing you to personalize voicemail messages with runtime values such as `{{user_name}}` or `{{appointment_time}}`

## API Implementation

When creating an agent via API, you can add the Voicemail Detection tool to your agent configuration. It should be defined as a system tool:

<CodeBlocks>
  ```python
  from elevenlabs import (
      ConversationalConfig,
      ElevenLabs,
      AgentConfig,
      PromptAgent,
      PromptAgentInputToolsItem_System
  )

  # Initialize the client
  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  # Create the voicemail detection tool
  voicemail_detection_tool = PromptAgentInputToolsItem_System(
      name="voicemail_detection",
      description=""  # Optional: Customize when the tool should be triggered
  )

  # Create the agent configuration
  conversation_config = ConversationalConfig(
      agent=AgentConfig(
          prompt=PromptAgent(
              tools=[voicemail_detection_tool]
          )
      )
  )

  # Create the agent
  response = elevenlabs.conversational_ai.agents.create(
      conversation_config=conversation_config
  )
  ```

  ```javascript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';

  // Initialize the client
  const elevenlabs = new ElevenLabs({
    apiKey: 'YOUR_API_KEY',
  });

  // Create the agent with voicemail detection tool
  await elevenlabs.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        prompt: {
          tools: [
            {
              type: 'system',
              name: 'voicemail_detection',
              description: '', // Optional: Customize when the tool should be triggered
            },
          ],
        },
      },
    },
  });
  ```
</CodeBlocks>


# Tool Call Sounds

> Add ambient audio during tool execution to enhance user experience.

## Overview

Tool call sounds provide ambient audio feedback during tool execution, creating a more natural and engaging conversation experience. When your agent executes a tool - such as fetching data from an API or processing a request - these sounds help fill moments of silence and indicate to users that the agent is actively working.

ElevenLabs Agents supports multiple built-in ambient sounds that you can configure at both the tool level and integration level, giving you fine-grained control over when and how sounds are played during your conversations.

## Use Cases

Tool call sounds are particularly effective in scenarios where:

* **API calls take time to complete**: Play ambient music or typing sounds while fetching data from external services
* **Long-running operations**: Provide audio feedback during database queries, complex calculations, or third-party integrations
* **Natural conversation flow**: Fill gaps in the conversation to prevent awkward silences
* **User expectations**: Signal to users that the agent is processing their request rather than experiencing technical issues

<Info>
  Tool call sounds are optional. If you prefer silent tool execution, simply leave the tool call
  sound setting as "None".
</Info>

## Available Sounds

ElevenLabs provides the following ambient audio options:

| Sound Type         | Description                     | Best For                           |
| ------------------ | ------------------------------- | ---------------------------------- |
| None               | No sound during tool execution  | Quick operations, silent workflows |
| Typing             | Keyboard typing sound effect    | Search queries, text processing    |
| Elevator Music 1-4 | Light background music (upbeat) | Longer wait times, general use     |

<Tip>
  You can preview each sound in the dashboard by clicking the play button next to the dropdown when
  configuring tool call sounds.
</Tip>

## Configuration

Tool call sounds can be configured in two places, with tool-level configuration taking precedence:

### Tool-Level Configuration

Configure sounds for individual tools in your agent's tool settings:

<Steps>
  <Step title="Navigate to tool configuration">
    In the **Agent** section of your agent settings, select the tool you want to configure or create a new tool.
  </Step>

  <Step title="Configure tool call sound">
    Scroll to the **Tool Call Sound** section at the bottom of the tool configuration.

    <Frame background="subtle">
      ![tool call sound dropdown](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/093fd6c380e2d51f0b8dbe152377a35e1e4e0e422638519910016b9f1551233d/assets/images/agents/tool-call-sounds-1.png)
    </Frame>

    Select a sound from the dropdown menu:

    * **None**: No sound will play
    * **Typing**: Keyboard typing effect
    * **Elevator Music 1-4**: Various ambient background music options
  </Step>

  <Step title="Configure sound behavior">
    If you've selected a sound (not "None"), you'll see an additional **Sound Behavior** option:

    <Frame background="subtle">
      ![sound behavior dropdown](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/00c7f6ddfb1b0240a900c8d6814c8706e045500d92f6a6c263d4a7c962e24fbe/assets/images/agents/tool-call-sounds-2.png)
    </Frame>

    Choose when the sound should play:

    * **With pre-speech**: Sound plays only when the agent speaks before executing the tool
    * **Always play**: Sound plays during every tool execution, regardless of whether the agent speaks first
  </Step>

  <Step title="Save your configuration">
    Click **Save** to apply your tool call sound settings.
  </Step>
</Steps>

### Integration-Level Configuration

For tools created through integrations (MCP servers, API integrations, etc.), you can set default tool call sounds at the integration level:

<Steps>
  <Step title="Navigate to integration settings">
    Go to **Agent Settings > Integrations** and select your integration.
  </Step>

  <Step title="Configure default sound">
    In the integration overview, locate the **Tool Call Sound** settings.

    <Frame background="subtle">
      ![tool call sound integrations dropdown](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9c4c33501c814c3d124d76060853ee6eb8c59c8b4f0cc494d16267e9fe5cf56b/assets/images/agents/tool-call-sounds-3.png)
    </Frame>

    Select a default sound that will apply to all tools from this integration unless overridden at the tool level.
  </Step>

  <Step title="Override at tool level (optional)">
    You can override the integration-level default for specific tools by configuring tool call sounds in the individual tool settings.
  </Step>
</Steps>

## Sound Behavior Options

The sound behavior setting determines when tool call sounds play during a conversation:

### With Pre-Speech (Auto)

**Default behavior**. The sound plays only when the agent speaks before using the tool.

**Example scenario:**

```
User: "What's the weather in Tokyo?"
Agent: "Let me check that for you..." [typing sound plays while fetching weather data]
Agent: "It's currently 72 degrees and sunny in Tokyo."
```

**When to use:**

* When you want sounds to play only after the agent has acknowledged the request
* For a more natural conversational flow where silence after user speech would be awkward
* When tool execution immediately follows agent speech

### Always Play

The sound plays during every tool execution, regardless of whether the agent speaks beforehand.

**Example scenario:**

```
User: "Check my order status"
[typing sound plays immediately while fetching order data]
Agent: "Your order #12345 shipped yesterday and will arrive tomorrow."
```

**When to use:**

* For operations that always take noticeable time
* When you want consistent audio feedback for every tool call
* For background operations that may not require agent acknowledgment

<Warning>
  If you select "Always play", the sound will play even when the agent doesn't speak before using
  the tool. This can result in sounds playing immediately after the user finishes speaking, which
  may feel abrupt in some conversational contexts.
</Warning>

## Best Practices

#### Match sounds to tool execution time

For quick operations (\< 1 second), consider using "None" or the typing sound. For longer operations (> 3 seconds), elevator music options provide better user experience.

#### Use "With pre-speech" for acknowledged actions

When your agent explicitly acknowledges a request before executing it, use the "With pre-speech" behavior to create a natural conversation flow:

```plaintext System prompt
When users request information, first acknowledge their request before using tools.
For example: "Let me check that for you..." then call the appropriate tool.
```

#### Configure at integration level for consistency

If you have multiple tools from the same integration, configure tool call sounds at the integration level to ensure consistent audio feedback across all related tools.

#### Test with realistic latencies

Test your tool call sounds with realistic API latencies to ensure the audio feedback matches user expectations. Consider:

* Network latency to your APIs
* API processing time
* Geographic distribution of your users

#### Balance with interruption handling

If your agent supports user interruptions, tool call sounds will be automatically stopped when the user interrupts. Ensure your conversation flow handles this gracefully.

## Example Configurations

### Search Agent

**Use case**: Agent that searches a knowledge base or database

**Configuration**:

* Tool call sound: **Typing**
* Sound behavior: **With pre-speech**
* System prompt includes: *"When users ask questions, say 'Let me search for that' before calling the search tool."*

### Customer Service Agent

**Use case**: Agent that checks order status, inventory, or customer records

**Configuration**:

* Tool call sound: **Elevator Music 3**
* Sound behavior: **Always play**
* Rationale: Operations may take 2-5 seconds, and background music provides better experience than silence

### Multi-Step Workflow

**Use case**: Agent that performs multiple sequential tool calls

**Configuration**:

* First tool: **Typing** with **With pre-speech**
* Subsequent tools: **Elevator Music 1** with **Always play**
* System prompt orchestrates: *"First acknowledge the request, then execute tools sequentially."*

## Programmatic Configuration

While tool call sounds are primarily configured through the dashboard, you can also set them programmatically when creating agents via the API:

```json
{
  "conversation_config": {
    "agent": {
      "tools": [
        {
          "type": "webhook",
          "name": "get_weather",
          "description": "Gets current weather data",
          "url": "https://api.weather.com/data",
          "tool_call_sound": "typing",
          "tool_call_sound_behavior": "auto"
        }
      ]
    }
  }
}
```

<Info>
  Refer to the [API Reference](/docs/api-reference/agents/create) for complete schema details.
</Info>

## Troubleshooting

### Sound not playing

**Possible causes:**

1. **No pre-speech**: If using "With pre-speech" behavior, the agent must speak before the tool executes. Update your system prompt to include acknowledgment.
2. **Quick execution**: If the tool completes in less than \~500ms, the sound may not have time to play noticeably.

## Related Resources

* [Server Tools](/docs/agents-platform/customization/tools/server-tools) - Learn how to configure webhook tools
* [Client Tools](/docs/agents-platform/customization/tools/client-tools) - Understand client-side tool execution
* [System Tools](/docs/agents-platform/customization/tools/system-tools) - Explore built-in platform tools
* [Best Practices](/docs/developers/guides/cookbooks/multi-context-web-socket) - General best practices for building conversational agents


# Personalization

> Learn how to personalize your agent's behavior using dynamic variables and overrides.

## Overview

Personalization allows you to adapt your agent's behavior for each individual user, enabling more natural and contextually relevant conversations. ElevenLabs offers multiple approaches to personalization:

1. **Dynamic Variables** - Inject runtime values into prompts and messages
2. **Overrides** - Completely replace system prompts or messages
3. **Twilio Integration** - Personalize inbound call experiences via webhooks

## Personalization Methods

<CardGroup cols={3}>
  <Card title="Dynamic Variables" icon="duotone lambda" href="/docs/agents-platform/customization/personalization/dynamic-variables">
    Define runtime values using `{{ var_name }}` syntax to personalize your agent's messages, system
    prompts, and tools.
  </Card>

  <Card title="Overrides" icon="duotone sliders" href="/docs/agents-platform/customization/personalization/overrides">
    Completely replace system prompts, first messages, language, or voice settings for each
    conversation.
  </Card>

  <Card title="Twilio Integration" icon="duotone phone-arrow-down-left" href="/docs/agents-platform/customization/personalization/twilio-personalization">
    Dynamically personalize inbound Twilio calls using webhook data.
  </Card>
</CardGroup>

## Conversation Initiation Client Data Structure

The `conversation_initiation_client_data` object defines what can be customized when starting a conversation:

```json
{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "overriding system prompt"
      },
      "first_message": "overriding first message",
      "language": "en"
    },
    "tts": {
      "voice_id": "voice-id-here"
    }
  },
  "custom_llm_extra_body": {
    "temperature": 0.7,
    "max_tokens": 100
  },
  "dynamic_variables": {
    "string_var": "text value",
    "number_var": 1.2,
    "integer_var": 123,
    "boolean_var": true
  },
  "user_id": "your_custom_user_id"
}
```

## Choosing the Right Approach

<Table>
  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Best For
      </th>

      <th>
        Implementation
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Dynamic Variables**
      </td>

      <td>
        * Inserting user-specific data into templated content - Maintaining consistent agent
          behavior with personalized details - Personalizing tool parameters
      </td>

      <td>
        Define variables with 

        `{{ variable_name }}`

         and pass values at runtime
      </td>
    </tr>

    <tr>
      <td>
        **Overrides**
      </td>

      <td>
        * Completely changing agent behavior per user - Switching languages or voices - Legacy
          applications (consider migrating to Dynamic Variables)
      </td>

      <td>
        Enable specific override permissions in security settings and pass complete replacement
        content
      </td>
    </tr>
  </tbody>
</Table>

## Learn More

* [Dynamic Variables Documentation](/docs/agents-platform/customization/personalization/dynamic-variables)
* [Overrides Documentation](/docs/agents-platform/customization/personalization/overrides)
* [Twilio Integration Documentation](/docs/agents-platform/customization/personalization/twilio-personalization)


# Dynamic variables

> Pass runtime values to personalize your agent's behavior.

**Dynamic variables** allow you to inject runtime values into your agent's messages, system prompts, and tools. This enables you to personalize each conversation with user-specific data without creating multiple agents.

## Overview

Dynamic variables can be integrated into multiple aspects of your agent:

* **System prompts** to customize behavior and context
* **First messages** to personalize greetings
* **Tool parameters and headers** to pass user-specific data

Here are a few examples where dynamic variables are useful:

* **Personalizing greetings** with user names
* **Including account details** in responses
* **Passing data** to tool calls
* **Customizing behavior** based on subscription tiers
* **Accessing system information** like conversation ID or call duration

<Info>
  Dynamic variables are ideal for injecting user-specific data that shouldn't be hardcoded into your
  agent's configuration.
</Info>

## System dynamic variables

Your agent has access to these automatically available system variables:

* `system__agent_id` - Unique identifier of the agent that initiated the conversation (stays stable throughout the conversation)
* `system__current_agent_id` - Unique identifier of the currently active agent (changes after agent transfers)
* `system__caller_id` - Caller's phone number (voice calls only)
* `system__called_number` - Destination phone number (voice calls only)
* `system__call_duration_secs` - Call duration in seconds
* `system__time_utc` - Current UTC time (ISO format)
* `system__time` - Current time in the specified timezone (human-readable format, e.g., "Friday, 12:33 12 December 2025")
* `system__timezone` - User-provided timezone (must be valid for tzinfo)
* `system__conversation_id` - ElevenLabs' unique conversation identifier
* `system__call_sid` - Call SID (twilio calls only)

System variables:

* Are available without runtime configuration
* Are prefixed with `system__` (reserved prefix)
* In system prompts: Set once at conversation start (value remains static)
* In tool calls: Updated at execution time (value reflects current state)

<Warning>
  Custom dynamic variables cannot use the reserved 

  `system__`

   prefix.
</Warning>

## Secret dynamic variables

Secret dynamic variables are populated in the same way as normal dynamic variables but indicate to our ElevenAgents that these should
only be used in dynamic variable headers and never sent to an LLM provider as part of an agent's system prompt or first message.

We recommend using these for auth tokens or private IDs that should not be sent to an LLM. To create a secret dynamic variable, simply prefix the dynamic variable with `secret__`.

## Updating dynamic variables from tools

[Tool calls](https://elevenlabs.io/docs/agents-platform/customization/tools) can create or update dynamic variables if they return a valid JSON object. To specify what should be extracted, set the object path(s) using dot notation. If the field or path doesn't exist, nothing is updated.

Example of a response object and dot notation:

* Status corresponds to the path: `response.status`
* The first user's email in the users array corresponds to the path: `response.users.0.email`

<CodeGroup>
  ```JSON title="JSON"
  {
    "response": {
      "status": 200,
      "message": "Successfully found 5 users",
      "users": [
        "user_1": {
          "user_name": "test_user_1",
          "email": "test_user_1@email.com"
        }
      ]
    }
  }
  ```
</CodeGroup>

To update a dynamic variable to be the first user's email, set the assignment like so.

<Frame background="subtle">
  ![Query parameters](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110/assets/images/conversational-ai/dv-assignment.png)
</Frame>

Assignments are a field of each server tool, that can be found documented [here](/docs/agents-platform/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments).

## Guide

### Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs Conversational Agent ([create one here](/docs/agents-platform/quickstart))

<Steps>
  <Step title="Define dynamic variables in prompts">
    Add variables using double curly braces `{{variable_name}}` in your:

    * System prompts
    * First messages
    * Tool parameters

    <Frame background="subtle">
      ![Dynamic variables in messages](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3/assets/images/conversational-ai/dynamic-vars-first-message.png)
    </Frame>

    <Frame background="subtle">
      ![Dynamic variables in messages](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe/assets/images/conversational-ai/dynamic-vars-system-prompt.png)
    </Frame>
  </Step>

  <Step title="Define dynamic variables in tools">
    You can also define dynamic variables in the tool configuration.
    To create a new dynamic variable, set the value type to Dynamic variable and click the `+` button.

    <Frame background="subtle">
      ![Setting placeholders](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd/assets/images/conversational-ai/dynamic-vars-config.png)
    </Frame>

    <Frame background="subtle">
      ![Setting placeholders](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713/assets/images/conversational-ai/dynamic-vars-path-params.png)
    </Frame>
  </Step>

  <Step title="Set placeholders">
    Configure default values in the web interface for testing:

    <Frame background="subtle">
      ![Setting placeholders](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4/assets/images/conversational-ai/dynamic-vars-presets.png)
    </Frame>
  </Step>

  <Step title="Pass variables at runtime">
    When starting a conversation, provide the dynamic variables in your code:

    <Tip>
      Ensure you have the latest [SDK](/docs/agents-platform/libraries/python) installed.
    </Tip>

    <CodeGroup>
      ```python title="Python" focus={10-23} maxLines=25
      import os
      import signal
      from elevenlabs.client import ElevenLabs
      from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
      from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

      agent_id = os.getenv("AGENT_ID")
      api_key = os.getenv("ELEVENLABS_API_KEY")
      elevenlabs = ElevenLabs(api_key=api_key)

      dynamic_vars = {
          "user_name": "Angelo",
      }

      config = ConversationInitiationData(
          dynamic_variables=dynamic_vars
      )

      conversation = Conversation(
          elevenlabs,
          agent_id,
          config=config,
          # Assume auth is required when API_KEY is set.
          requires_auth=bool(api_key),
          # Use the default audio interface.
          audio_interface=DefaultAudioInterface(),
          # Simple callbacks that print the conversation to the console.
          callback_agent_response=lambda response: print(f"Agent: {response}"),
          callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
          callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
          # Uncomment the below if you want to see latency measurements.
          # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
      )

      conversation.start_session()

      signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())
      ```

      ```javascript title="JavaScript" focus={7-20} maxLines=25
      import { Conversation } from '@elevenlabs/client';

      class VoiceAgent {
        ...

        async startConversation() {
          try {
              // Request microphone access
              await navigator.mediaDevices.getUserMedia({ audio: true });

              this.conversation = await Conversation.startSession({
                  agentId: 'agent_id_goes_here', // Replace with your actual agent ID

                  dynamicVariables: {
                      user_name: 'Angelo'
                  },

                  ... add some callbacks here
              });
          } catch (error) {
              console.error('Failed to start conversation:', error);
              alert('Failed to start conversation. Please ensure microphone access is granted.');
          }
        }
      }
      ```

      ```swift title="Swift"
      let dynamicVars: [String: DynamicVariableValue] = [
        "customer_name": .string("John Doe"),
        "account_balance": .number(5000.50),
        "user_id": .int(12345),
        "is_premium": .boolean(true)
      ]

      // Create session config with dynamic variables
      let config = SessionConfig(
          agentId: "your_agent_id",
          dynamicVariables: dynamicVars
      )

      // Start the conversation
      let conversation = try await Conversation.startSession(
          config: config
      )
      ```

      ```html title="Widget"
      <elevenlabs-convai
        agent-id="your-agent-id"
        dynamic-variables='{"user_name": "John", "account_type": "premium"}'
      ></elevenlabs-convai>
      ```
    </CodeGroup>
  </Step>
</Steps>

## Public Talk-to Page Integration

The public talk-to page supports dynamic variables through URL parameters, enabling you to personalize conversations when sharing agent links. This is particularly useful for embedding personalized agents in websites, emails, or marketing campaigns.

### URL Parameter Methods

There are two methods to pass dynamic variables to the public talk-to page:

#### Method 1: Base64-Encoded JSON

Pass variables as a base64-encoded JSON object using the `vars` parameter:

```
https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
```

The `vars` parameter contains base64-encoded JSON:

```json
{ "user_name": "John", "account_type": "premium" }
```

#### Method 2: Individual Query Parameters

Pass variables using `var_` prefixed query parameters:

```
https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&var_user_name=John&var_account_type=premium
```

### Parameter Precedence

When both methods are used simultaneously, individual `var_` parameters take precedence over the base64-encoded variables to prevent conflicts:

```
https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John
```

In this example, `user_name` will be "John" (from `var_user_name`) instead of "Jane" (from the base64-encoded `vars`).

### Implementation Examples

<Tabs>
  <Tab title="JavaScript URL Generation">
    ```javascript
    // Method 1: Base64-encoded JSON
    function generateTalkToURL(agentId, variables) {
      const baseURL = 'https://elevenlabs.io/app/talk-to';
      const encodedVars = btoa(JSON.stringify(variables));
      return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
    }

    // Method 2: Individual parameters
    function generateTalkToURLWithParams(agentId, variables) {
      const baseURL = 'https://elevenlabs.io/app/talk-to';
      const params = new URLSearchParams({ agent_id: agentId });

      Object.entries(variables).forEach(([key, value]) => {
        params.append(`var_${key}`, encodeURIComponent(value));
      });

      return `${baseURL}?${params.toString()}`;
    }

    // Usage
    const variables = {
      user_name: "John Doe",
      account_type: "premium",
      session_id: "sess_123"
    };

    const urlMethod1 = generateTalkToURL("your_agent_id", variables);
    const urlMethod2 = generateTalkToURLWithParams("your_agent_id", variables);
    ```
  </Tab>

  <Tab title="Python URL Generation">
    ```python
    import base64
    import json
    from urllib.parse import urlencode, quote

    def generate_talk_to_url(agent_id, variables):
        """Generate URL with base64-encoded variables"""
        base_url = "https://elevenlabs.io/app/talk-to"
        encoded_vars = base64.b64encode(json.dumps(variables).encode()).decode()
        return f"{base_url}?agent_id={agent_id}&vars={encoded_vars}"

    def generate_talk_to_url_with_params(agent_id, variables):
        """Generate URL with individual var_ parameters"""
        base_url = "https://elevenlabs.io/app/talk-to"
        params = {"agent_id": agent_id}

        for key, value in variables.items():
            params[f"var_{key}"] = value

        return f"{base_url}?{urlencode(params)}"

    # Usage
    variables = {
        "user_name": "John Doe",
        "account_type": "premium",
        "session_id": "sess_123"
    }

    url_method1 = generate_talk_to_url("your_agent_id", variables)
    url_method2 = generate_talk_to_url_with_params("your_agent_id", variables)
    ```
  </Tab>

  <Tab title="Manual URL Construction">
    ```
    # Base64-encoded method
    1. Create JSON: {"user_name": "John", "account_type": "premium"}
    2. Encode to base64: eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
    3. Add to URL: https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

    # Individual parameters method
    1. Add each variable with var_ prefix
    2. URL encode values if needed
    3. Final URL: https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&var_user_name=John&var_account_type=premium
    ```
  </Tab>
</Tabs>

## Supported Types

Dynamic variables support these value types:

<CardGroup cols={3}>
  <Card title="String">
    Text values
  </Card>

  <Card title="Number">
    Numeric values
  </Card>

  <Card title="Boolean">
    True/false values
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variables not replacing">
    Verify that:

    * Variable names match exactly (case-sensitive)
    * Variables use double curly braces: `{{ variable_name }}`
    * Variables are included in your dynamic\_variables object
  </Accordion>

  <Accordion title="Type errors">
    Ensure that:

    * Variable values match the expected type
    * Values are strings, numbers, or booleans only
  </Accordion>
</AccordionGroup>


# Overrides

> Tailor each conversation with personalized context for each user.

<Warning>
  While overrides are still supported for completely replacing system prompts or first messages, we
  recommend using [Dynamic
  Variables](/docs/agents-platform/customization/personalization/dynamic-variables) as the preferred
  way to customize your agent's responses and inject real-time data. Dynamic Variables offer better
  maintainability and a more structured approach to personalization.
</Warning>

**Overrides** enable your assistant to adapt its behavior for each user interaction. You can pass custom data and settings at the start of each conversation, allowing the assistant to personalize its responses and knowledge with real-time context. Overrides completely override the agent's default values defined in the agent's [dashboard](https://elevenlabs.io/app/agents/agents).

## Overview

Overrides allow you to modify your AI agent's behavior in real-time without creating multiple agents. This enables you to personalize responses with user-specific data.

Overrides can be enabled for the following fields in the agent's security settings:

* System prompt
* First message
* Language
* Voice ID
* LLM (Large Language Model)
* Text-only mode
* Voice ID
* Stability
* Speed
* Similarity boost

When overrides are enabled for a field, providing an override is still optional. If not provided, the agent will use the default values defined in the agent's [dashboard](https://elevenlabs.io/app/agents/agents). An error will be thrown if an override is provided for a field that does not have overrides enabled.

Here are a few examples where overrides can be useful:

* **Greet users** by their name
* **Include account-specific details** in responses
* **Adjust the agent's language** or tone based on user preferences
* **Pass real-time data** like account balances or order status

<Info>
  Overrides are particularly useful for applications requiring personalized interactions or handling
  sensitive user data that shouldn't be stored in the agent's base configuration.
</Info>

## Guide

### Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs Conversational Agent ([create one here](/docs/agents-platform/quickstart))

This guide will show you how to override the default agent **System prompt**, **First message**, **LLM**, and **TTS settings**.

<Steps>
  <Step title="Enable overrides">
    For security reasons, overrides are disabled by default. Navigate to your agent's settings and
    select the **Security** tab.

    Enable the `First message`, `System prompt`, and any other overrides you need (such as `LLM`).

    <Frame background="subtle">
      ![Enable overrides](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/496f20380ffe29fc46275bbfe5c6eaabdb5e211c780188243a018b38715ea779/assets/images/conversational-ai/enable-overrides.jpg)
    </Frame>
  </Step>

  <Step title="Override the conversation">
    In your code, where the conversation is started, pass the overrides as a parameter.

    <Tip>
      Ensure you have the latest [SDK](/docs/agents-platform/libraries/python) installed.
    </Tip>

    <CodeGroup>
      ```python title="Python" focus={3-16} maxLines=16
      from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
      ...
      conversation_override = {
          "agent": {
              "prompt": {
                  "prompt": f"The customer's bank account balance is {customer_balance}. They are based in {customer_location}.", # Optional: override the system prompt.
                  "llm": "gpt-4o" # Optional: override the LLM model.
              },
              "first_message": f"Hi {customer_name}, how can I help you today?", # Optional: override the first_message.
              "language": "en" # Optional: override the language.
          },
          "tts": {
              "voice_id": "custom_voice_id", # Optional: override the voice.
              "stability": 0.7, # Optional: override stability (0.0 to 1.0).
              "speed": 1.1, # Optional: override speed (0.7 to 1.2).
              "similarity_boost": 0.9 # Optional: override similarity boost (0.0 to 1.0).
          },
          "conversation": {
              "text_only": True # Optional: enable text-only mode (no audio).
          }
      }

      config = ConversationInitiationData(
          conversation_config_override=conversation_override
      )
      conversation = Conversation(
          ...
          config=config,
          ...
      )
      conversation.start_session()
      ```

      ```javascript title="JavaScript" focus={4-17} maxLines=17
      ...
      const conversation = await Conversation.startSession({
        ...
        overrides: {
            agent: {
                prompt: {
                    prompt: `The customer's bank account balance is ${customer_balance}. They are based in ${customer_location}.`, // Optional: override the system prompt.
                    llm: "gpt-4o" // Optional: override the LLM model.
                },
                firstMessage: `Hi ${customer_name}, how can I help you today?`, // Optional: override the first message.
                language: "en" // Optional: override the language.
            },
            tts: {
                voiceId: "custom_voice_id", // Optional: override the voice.
                stability: 0.7, // Optional: override stability (0.0 to 1.0).
                speed: 1.1, // Optional: override speed (0.7 to 1.2).
                similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
            },
            conversation: {
                textOnly: true // Optional: enable text-only mode (no audio).
            }
        },
        ...
      })
      ```

      ```swift title="Swift" focus={3-16} maxLines=16
      import ElevenLabsSDK

      let promptOverride = ElevenLabsSDK.AgentPrompt(
          prompt: "The customer's bank account balance is \(customer_balance). They are based in \(customer_location).", // Optional: override the system prompt.
          llm: "gpt-4o" // Optional: override the LLM model.
      )
      let agentConfig = ElevenLabsSDK.AgentConfig(
          prompt: promptOverride, // Optional: override the system prompt.
          firstMessage: "Hi \(customer_name), how can I help you today?", // Optional: override the first message.
          language: .en // Optional: override the language.
      )
      let ttsConfig = ElevenLabsSDK.TTSConfig(
          voiceId: "custom_voice_id", // Optional: override the voice.
          stability: 0.7, // Optional: override stability (0.0 to 1.0).
          speed: 1.1, // Optional: override speed (0.7 to 1.2).
          similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
      )
      let conversationConfig = ElevenLabsSDK.ConversationConfig(
          textOnly: true // Optional: enable text-only mode (no audio).
      )
      let overrides = ElevenLabsSDK.ConversationConfigOverride(
          agent: agentConfig, // Optional: override agent settings.
          tts: ttsConfig, // Optional: override TTS settings.
          conversation: conversationConfig // Optional: override conversation settings.
      )

      let config = ElevenLabsSDK.SessionConfig(
          agentId: "",
          overrides: overrides
      )

      let conversation = try await ElevenLabsSDK.Conversation.startSession(
        config: config,
        callbacks: callbacks
      )
      ```

      ```html title="Widget"
        <elevenlabs-convai
          agent-id="your-agent-id"
          override-language="es"         <!-- Optional: override the language -->
          override-prompt="Custom system prompt for this user"  <!-- Optional: override the system prompt -->
          override-first-message="Hi! How can I help you today?"  <!-- Optional: override the first message -->
          override-voice-id="custom_voice_id"  <!-- Optional: override the voice -->
        ></elevenlabs-convai>
      ```
    </CodeGroup>

    <Note>
      When using overrides, omit any fields you don't want to override rather than setting them to empty strings or null values. Only include the fields you specifically want to customize.
    </Note>

    <Tip>
      To find the correct LLM model string, refer to the [Agent API reference](/docs/api-reference/agents/create#request.body.conversation_config.agent.prompt.llm) which lists all supported LLM models and their exact string identifiers.
    </Tip>
  </Step>
</Steps>


# Twilio personalization

> Configure personalization for incoming Twilio calls using webhooks.

## Overview

When receiving inbound Twilio calls, you can dynamically fetch conversation initiation data through a webhook. This allows you to customize your agent's behavior based on caller information and other contextual data.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/cAuSo8qNs-8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## How it works

1. When a Twilio call is received, ElevenAgents will make a webhook call to your specified endpoint, passing call information (`caller_id`, `agent_id`, `called_number`, `call_sid`) as arguments
2. Your webhook returns conversation initiation client data, including dynamic variables and overrides (an example is shown below)
3. This data is used to initiate the conversation

<Tip>
  The system uses Twilio's connection/dialing period to fetch webhook data in parallel, creating a
  seamless experience where:

  * Users hear the expected telephone connection sound
  * In parallel, ElevenAgents fetches necessary webhook data
  * The conversation is initiated with the fetched data by the time the audio connection is established
</Tip>

## Configuration

<Steps>
  <Step title="Configure webhook details">
    In the [settings page](https://elevenlabs.io/app/agents/settings) of ElevenAgents, configure the webhook URL and add any
    secrets needed for authentication.

    <Frame background="subtle">
      ![Enable webhook](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/53e98b709e5751bfb6cf6758372a8105c5408b20191523c7e91c2a7625d8b603/assets/images/conversational-ai/convai-settings.png)
    </Frame>

    Click on the webhook to modify which secrets are sent in the headers.

    <Frame background="subtle">
      ![Add secrets to headers](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/416d30e6906cd209de92820bfc146ac9478fbb6ce61c8fbbc24d62cad54d9f05/assets/images/conversational-ai/convai-initiation-webhook.png)
    </Frame>
  </Step>

  <Step title="Enable fetching conversation initiation data">
    In the "Security" tab of the [agent's page](https://elevenlabs.io/app/agents/agents/), enable fetching conversation initiation data for inbound Twilio calls, and define fields that can be overridden.

    <Frame background="subtle">
      ![Enable webhook](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6024b7f7541b8f856514b56ebf391cd6ee24206fd89c07327de1b01d81795c20/assets/images/conversational-ai/enable-twilio-webhook.png)
    </Frame>
  </Step>

  <Step title="Implement the webhook endpoint to receive Twilio data">
    The webhook will receive a POST request with the following parameters:

    | Parameter       | Type   | Description                            |
    | --------------- | ------ | -------------------------------------- |
    | `caller_id`     | string | The phone number of the caller         |
    | `agent_id`      | string | The ID of the agent receiving the call |
    | `called_number` | string | The Twilio number that was called      |
    | `call_sid`      | string | Unique identifier for the Twilio call  |
  </Step>

  <Step title="Return conversation initiation client data">
    Your webhook must return a JSON response containing the initiation data for the agent.

    <Info>
      The `dynamic_variables` field must contain all dynamic variables defined for the agent. Overrides
      on the other hand are entirely optional. For more information about dynamic variables and
      overrides see the [dynamic variables](/docs/agents-platform/customization/personalization/dynamic-variables) and
      [overrides](/docs/agents-platform/customization/personalization/overrides) docs.
    </Info>

    An example response could be:

    ```json
    {
      "type": "conversation_initiation_client_data",
      "dynamic_variables": {
        "customer_name": "John Doe",
        "account_status": "premium",
        "last_interaction": "2024-01-15"
      },
      "conversation_config_override": {
        "agent": {
          "prompt": {
            "prompt": "The customer's bank account balance is $100. They are based in San Francisco."
          },
          "first_message": "Hi, how can I help you today?",
          "language": "en"
        },
        "tts": {
          "voice_id": "new-voice-id"
        }
      }
    }
    ```
  </Step>
</Steps>

ElevenAgents will use the dynamic variables to populate the conversation initiation data, and the conversation will start smoothly.

<Warning>
  Ensure your webhook responds within a reasonable timeout period to avoid delaying the call
  handling.
</Warning>

## Security

* Use HTTPS endpoints only
* Implement authentication using request headers
* Store sensitive values as secrets through the [ElevenLabs secrets manager](https://elevenlabs.io/app/agents/settings)
* Validate the incoming request parameters


# Agent authentication

> Learn how to secure access to your conversational agents

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/8hZ4IWL7iqw?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

When building conversational agents, you may need to restrict access to certain agents or conversations. ElevenLabs provides multiple authentication mechanisms to ensure only authorized users can interact with your agents.

## Authentication methods

ElevenLabs offers two primary methods to secure your conversational agents:

<CardGroup cols={2}>
  <Card title="Signed URLs" icon="signature" href="#using-signed-urls">
    Generate temporary authenticated URLs for secure client-side connections without exposing API
    keys.
  </Card>

  <Card title="Allowlists" icon="list-check" href="#using-allowlists">
    Restrict access to specific domains or hostnames that can connect to your agent.
  </Card>
</CardGroup>

## Using signed URLs

Signed URLs are the recommended approach for client-side applications. This method allows you to authenticate users without exposing your API key.

<Note>
  The guides below uses the [JS client](https://www.npmjs.com/package/@elevenlabs/client) and
  [Python SDK](https://github.com/elevenlabs/elevenlabs-python/).
</Note>

### How signed URLs work

1. Your server requests a signed URL from ElevenLabs using your API key.
2. ElevenLabs generates a temporary token and returns a signed WebSocket URL.
3. Your client application uses this signed URL to establish a WebSocket connection.
4. The signed URL expires after 15 minutes.

<Warning>
  Never expose your ElevenLabs API key client-side.
</Warning>

### Generate a signed URL via the API

To obtain a signed URL, make a request to the `get_signed_url` [endpoint](/docs/agents-platform/api-reference/conversations/get-signed-url) with your agent ID:

<CodeBlocks>
  ```python
  # Server-side code using the Python SDK
  from elevenlabs.client import ElevenLabs
  async def get_signed_url():
      try:
          elevenlabs = ElevenLabs(api_key="your-api-key")
          response = await elevenlabs.conversational_ai.conversations.get_signed_url(agent_id="your-agent-id")
          return response.signed_url
      except Exception as error:
          print(f"Error getting signed URL: {error}")
          raise
  ```

  ```javascript
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

  // Server-side code using the JavaScript SDK
  const elevenlabs = new ElevenLabsClient({ apiKey: 'your-api-key' });
  async function getSignedUrl() {
    try {
      const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
        agentId: 'your-agent-id',
      });

      return response.signed_url;
    } catch (error) {
      console.error('Error getting signed URL:', error);
      throw error;
    }
  }
  ```

  ```bash
  curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=your-agent-id" \
  -H "xi-api-key: your-api-key"
  ```
</CodeBlocks>

The curl response has the following format:

```json
{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=your-agent-id&conversation_signature=your-token"
}
```

### Connecting to your agent using a signed URL

Retrieve the server generated signed URL from the client and use the signed URL to connect to the websocket.

<CodeBlocks>
  ```python
  # Client-side code using the Python SDK
  from elevenlabs.conversational_ai.conversation import (
      Conversation,
      AudioInterface,
      ClientTools,
      ConversationInitiationData
  )
  import os
  from elevenlabs.client import ElevenLabs
  api_key = os.getenv("ELEVENLABS_API_KEY")

  elevenlabs = ElevenLabs(api_key=api_key)

  conversation = Conversation(
    client=elevenlabs,
    agent_id=os.getenv("AGENT_ID"),
    requires_auth=True,
    audio_interface=AudioInterface(),
    config=ConversationInitiationData()
  )

  async def start_conversation():
    try:
      signed_url = await get_signed_url()
      conversation = Conversation(
        client=elevenlabs,
        url=signed_url,
      )

      conversation.start_session()
    except Exception as error:
      print(f"Failed to start conversation: {error}")

  ```

  ```javascript
  // Client-side code using the JavaScript SDK
  import { Conversation } from '@elevenlabs/client';

  async function startConversation() {
    try {
      const signedUrl = await getSignedUrl();
      const conversation = await Conversation.startSession({
        signedUrl,
      });

      return conversation;
    } catch (error) {
      console.error('Failed to start conversation:', error);
      throw error;
    }
  }
  ```
</CodeBlocks>

### Signed URL expiration

Signed URLs are valid for 15 minutes. The conversation session can last longer, but the conversation must be initiated within the 15 minute window.

## Using allowlists

Allowlists provide a way to restrict access to your conversational agents based on the origin domain. This ensures that only requests from approved domains can connect to your agent.

### How allowlists work

1. You configure a list of approved hostnames for your agent.
2. When a client attempts to connect, ElevenLabs checks if the request's origin matches an allowed hostname.
3. If the origin is on the allowlist, the connection is permitted; otherwise, it's rejected.

### Configuring allowlists

Allowlists are configured as part of your agent's authentication settings. You can specify up to 10 unique hostnames that are allowed to connect to your agent.

### Example: setting up an allowlist

<CodeBlocks>
  ```python
  from elevenlabs.client import ElevenLabs
  import os
  from elevenlabs.types import *

  api_key = os.getenv("ELEVENLABS_API_KEY")
  elevenlabs = ElevenLabs(api_key=api_key)

  agent = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
      agent=AgentConfig(
        first_message="Hi. I'm an authenticated agent.",
      )
    ),
    platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      enable_auth=False,
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
        AllowlistItem(hostname="localhost:3000")
        ]
      )
    )
  )
  ```

  ```javascript
  async function createAuthenticatedAgent(client) {
    try {
      const agent = await elevenlabs.conversationalAi.agents.create({
        conversationConfig: {
          agent: {
            firstMessage: "Hi. I'm an authenticated agent.",
          },
        },
        platformSettings: {
          auth: {
            enableAuth: false,
            allowlist: [
              { hostname: 'example.com' },
              { hostname: 'app.example.com' },
              { hostname: 'localhost:3000' },
            ],
          },
        },
      });

      return agent;
    } catch (error) {
      console.error('Error creating agent:', error);
      throw error;
    }
  }
  ```
</CodeBlocks>

## Combining authentication methods

For maximum security, you can combine both authentication methods:

1. Use `enable_auth` to require signed URLs.
2. Configure an allowlist to restrict which domains can request those signed URLs.

This creates a two-layer authentication system where clients must:

* Connect from an approved domain
* Possess a valid signed URL

<CodeBlocks>
  ```python
  from elevenlabs.client import ElevenLabs
  import os
  from elevenlabs.types import *
  api_key = os.getenv("ELEVENLABS_API_KEY")
  elevenlabs = ElevenLabs(api_key=api_key)
  agent = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
      agent=AgentConfig(
        first_message="Hi. I'm an authenticated agent that can only be called from certain domains.",
      )
    ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      enable_auth=True,
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
        AllowlistItem(hostname="localhost:3000")
      ]
    )
  )
  ```

  ```javascript
  async function createAuthenticatedAgent(elevenlabs) {
    try {
      const agent = await elevenlabs.conversationalAi.agents.create({
        conversationConfig: {
          agent: {
            firstMessage: "Hi. I'm an authenticated agent.",
          },
        },
        platformSettings: {
          auth: {
            enableAuth: true,
            allowlist: [
              { hostname: 'example.com' },
              { hostname: 'app.example.com' },
              { hostname: 'localhost:3000' },
            ],
          },
        },
      });

      return agent;
    } catch (error) {
      console.error('Error creating agent:', error);
      throw error;
    }
  }
  ```
</CodeBlocks>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use the same signed URL for multiple users?">
    This is possible but we recommend generating a new signed URL for each user session.
  </Accordion>

  <Accordion title="What happens if the signed URL expires during a conversation?">
    If the signed URL expires (after 15 minutes), any WebSocket connection created with that signed
    url will **not** be closed, but trying to create a new connection with that signed URL will
    fail.
  </Accordion>

  <Accordion title="Can I restrict access to specific users?">
    The signed URL mechanism only verifies that the request came from an authorized source. To
    restrict access to specific users, implement user authentication in your application before
    requesting the signed URL.
  </Accordion>

  <Accordion title="Is there a limit to how many signed URLs I can generate?">
    There is no specific limit on the number of signed URLs you can generate.
  </Accordion>

  <Accordion title="How do allowlists handle subdomains?">
    Allowlists perform exact matching on hostnames. If you want to allow both a domain and its
    subdomains, you need to add each one separately (e.g., "example.com" and "app.example.com").
  </Accordion>

  <Accordion title="Do I need to use both authentication methods?">
    No, you can use either signed URLs or allowlists independently based on your security
    requirements. For highest security, we recommend using both.
  </Accordion>

  <Accordion title="What other security measures should I implement?">
    Beyond signed URLs and allowlists, consider implementing:

    * User authentication before requesting signed URLs
    * Rate limiting on API requests
    * Usage monitoring for suspicious patterns
    * Proper error handling for auth failures
  </Accordion>
</AccordionGroup>


# Integrate

> Deploy your agents across web, mobile, and telephony platforms.

The Integrate section provides everything you need to connect your agents to your users, whether through web widgets, mobile apps, phone systems, or custom integrations.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/17a81505a62493491ead763b307b1e854825a0da67ab1a1d86b41b57ad87bc73/assets/images/agents/agents-overview-integrate.png" alt="Integration options" />
</Frame>

### Connect and deploy

| Goal                        | Guide                                                                               | Description                                                        |
| --------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Build with React components | [ElevenLabs UI](https://ui.elevenlabs.io)                                           | Pre-built components library for audio & agent apps (shadcn-based) |
| Embed widget in website     | [Widget](/docs/agents-platform/customization/widget)                                | Add a customizable web widget to any website                       |
| Build React web apps        | [React SDK](/docs/agents-platform/libraries/react)                                  | Voice-enabled React hooks and components                           |
| Build iOS apps              | [Swift SDK](/docs/agents-platform/libraries/swift)                                  | Native iOS SDK for voice agents                                    |
| Build Android apps          | [Kotlin SDK](/docs/agents-platform/libraries/kotlin)                                | Native Android SDK for voice agents                                |
| Build React Native apps     | [React Native SDK](/docs/agents-platform/libraries/react-native)                    | Cross-platform iOS and Android with React Native                   |
| Connect via SIP trunk       | [SIP trunk](/docs/agents-platform/phone-numbers/sip-trunking)                       | Integrate with existing telephony infrastructure                   |
| Make batch outbound calls   | [Batch calls](/docs/agents-platform/phone-numbers/batch-calls)                      | Trigger multiple calls programmatically                            |
| Use Twilio integration      | [Twilio](/docs/agents-platform/phone-numbers/twilio-integration/native-integration) | Native Twilio integration for phone calls                          |
| Build custom integrations   | [WebSocket API](/docs/agents-platform/libraries/web-sockets)                        | Low-level WebSocket protocol for custom implementations            |
| Receive real-time events    | [Events](/docs/agents-platform/customization/events)                                | Subscribe to conversation events and updates                       |

## Demo

This is a Next.js component from [ElevenLabs UI](https://ui.elevenlabs.io/blocks#voice-chat-01). View the source code to integrate it into your application.

<iframe src="https://ui.elevenlabs.io/view/voice-chat-01" width="100%" height="600" allow="microphone; autoplay" />

## Next steps

<CardGroup cols={2}>
  <Card title="Widget" href="/docs/agents-platform/customization/widget">
    Add a web widget to your site
  </Card>

  <Card title="React SDK" href="/docs/agents-platform/libraries/react">
    Build with React components
  </Card>

  <Card title="Twilio" href="/docs/agents-platform/phone-numbers/twilio-integration/native-integration">
    Deploy over phone
  </Card>

  <Card title="WebSocket API" href="/docs/agents-platform/libraries/web-sockets">
    Build custom integrations
  </Card>

  <Card title="ElevenLabs UI" href="https://ui.elevenlabs.io">
    Pre-built React components
  </Card>
</CardGroup>


# Widget customization

> Learn how to customize the widget appearance to match your brand, and personalize the agent's behavior from html.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/XweA70b45Ws?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

**Widgets** enable instant integration of ElevenAgents into any website. You can either customize your widget through the UI or through our type-safe [ElevenAgents SDKs](/docs/developers/resources/libraries) for complete control over styling and behavior. The SDK overrides take priority over UI customization.
Our widget is multimodal and able to process both text and audio.

<Frame caption="Multimodal conversational agents " background="subtle">
  <iframe width="100%" height="400" src="https://www.youtube.com/embed/TyPbeheubcs" title="Multimodal conversational agents" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />
</Frame>

## Modality configuration

The widget supports flexible input modes to match your use case. Configure these options in the [dashboard](https://elevenlabs.io/app/agents/dashboard) **Widget** tab under the **Interface** section.

<Note>
  Multimodality is fully supported in our client SDKs, see more
  [here](/docs/developers/resources/libraries).
</Note>

<Frame background="subtle">
  ![Widget interface options](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/cf851dd7a29b4bd23f7d36097ebf57c0bfe1b6a7a3b35687ddea20d9920a93c0/assets/images/conversational-ai/widget-options.png)
</Frame>

**Available modes:**

* **Voice only** (default): Users interact through speech only.
* **Voice + text**: Users can switch between voice and text input during conversations.
* **Chat Mode**: Conversations start in chat (text-only) mode without voice capabilities when initiated with a text message.

For more information on using chat (text-only) mode via our SDKs, see our [chat mode guide](/docs/agents-platform/guides/chat-mode).

<Note>
  The widget defaults to voice-only mode. Enable the text input toggle to allow multimodal
  interactions, or enable text-only mode support for purely text-based conversations when initiated
  via text.
</Note>

## Embedding the widget

<Note>
  Widgets currently require public agents with authentication disabled. Ensure this is disabled in
  the **Advanced** tab of your agent settings.
</Note>

Add this code snippet to your website's `<body>` section. Place it in your main `index.html` file for site-wide availability:

<CodeBlocks>
  ```html title="Widget embed code"
  <elevenlabs-convai agent-id="<replace-with-your-agent-id>"></elevenlabs-convai>
  <script
    src="https://unpkg.com/@elevenlabs/convai-widget-embed"
    async
    type="text/javascript"
  ></script>
  ```
</CodeBlocks>

<Info>
  For enhanced security, define allowed domains in your agent's **Allowlist** (located in the
  **Security** tab). This restricts access to specified hosts only.
</Info>

## Widget attributes

This basic embed code will display the widget with the default configuration defined in the agent's dashboard.
The widget supports various HTML attributes for further customization:

<AccordionGroup>
  <Accordion title="Core configuration">
    ```html
    <elevenlabs-convai
      agent-id="agent_id"              // Required: Your agent ID
      signed-url="signed_url"          // Alternative to agent-id
      server-location="us"             // Optional: "us" or default
      variant="expanded"               // Optional: Widget display mode
      dismissible="true"               // Optional: Allow the user to minimize the widget
    ></elevenlabs-convai>
    ```
  </Accordion>

  <Accordion title="Visual customization">
    ```html
    <elevenlabs-convai
      avatar-image-url="https://..." // Optional: Custom avatar image
      avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
      avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
    ></elevenlabs-convai>
    ```
  </Accordion>

  <Accordion title="Text customization">
    ```html
    <elevenlabs-convai
      action-text="Need assistance?" // Optional: CTA button text
      start-call-text="Begin conversation" // Optional: Start call button
      end-call-text="End call" // Optional: End call button
      expand-text="Open chat" // Optional: Expand widget text
      listening-text="Listening..." // Optional: Listening state
      speaking-text="Assistant speaking" // Optional: Speaking state
    ></elevenlabs-convai>
    ```
  </Accordion>

  <Accordion title="Markdown rendering">
    The widget renders markdown in agent responses. Links display as plain text by default to prevent phishing.

    ```html
    <elevenlabs-convai
      markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
      markdown-link-include-www="true"           // Also allow www variants (default: true)
      markdown-link-allow-http="true"            // Allow http:// links (default: true)
      syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
    ></elevenlabs-convai>
    ```
  </Accordion>
</AccordionGroup>

## Runtime configuration

Two more html attributes can be used to customize the agent's behavior at runtime. These two features can be used together, separately, or not at all

### Dynamic variables

Dynamic variables allow you to inject runtime values into your agent's messages, system prompts, and tools.

```html
<elevenlabs-convai
  agent-id="your-agent-id"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>
```

All dynamic variables that the agent requires must be passed in the widget.

<Info>
  See more in our [dynamic variables
  guide](/docs/agents-platform/customization/personalization/dynamic-variables).
</Info>

### Overrides

Overrides enable complete customization of your agent's behavior at runtime:

```html
<elevenlabs-convai
  agent-id="your-agent-id"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>
```

Overrides can be enabled for specific fields, and are entirely optional.

<Info>
  See more in our [overrides guide](/docs/agents-platform/customization/personalization/overrides).
</Info>

## Visual customization

Customize the widget's appearance, text content, language selection, and more in the [dashboard](https://elevenlabs.io/app/agents/dashboard) **Widget** tab.

<Frame background="subtle">
  ![Widget customization](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1f773d01a3c0925a47f11cf57153db23bc8bc03b93efe5d7085919886ae392cf/assets/images/conversational-ai/widget-overview.png)
</Frame>

<Tabs>
  <Tab title="Appearance">
    Customize the widget colors and shapes to match your brand identity.

    <Frame background="subtle">
      ![Widget appearance](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0c07c4569f8c5ad3b93933711c268601af411085aa7df1bb8e8ec547a01f2d8e/assets/images/conversational-ai/appearance.gif)
    </Frame>
  </Tab>

  <Tab title="Feedback">
    Gather user insights to improve agent performance. This can be used to fine-tune your agent's knowledge-base & system prompt.

    <Frame background="subtle">
      ![Widget feedback](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d7117399e23f06522b3112ff5c5ead23f66d3ea4700c011ff75e5dcd6cce875c/assets/images/conversational-ai/widget-feedback.png)
    </Frame>

    **Collection modes**

    * <strong>None</strong>: Disable feedback collection entirely.
    * <strong>During conversation</strong>: Support real-time feedback during conversations. Additionnal metadata such as the agent response that prompted the feedback will be collected to help further identify gaps.
    * <strong>After conversation</strong>: Display a single feedback prompt after the conversation.

    <Note>
      Send feedback programmatically via the [API](/docs/agents-platform/api-reference/conversations/create) when using custom SDK implementations.
    </Note>
  </Tab>

  <Tab title="Avatar">
    Configure the voice orb or provide your own avatar.

    <Frame background="subtle">
      ![Widget orb customization](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7530f28ad124fc4533911eca4a2269ac1df19dffd2b6dab1e8b56d95cc1eb53c/assets/images/conversational-ai/avatar.gif)
    </Frame>

    **Available options**

    * <strong>Orb</strong>: Choose two gradient colors (e.g., #6DB035 & #F5CABB).
    * <strong>Link/image</strong>: Use a custom avatar image.
  </Tab>

  <Tab title="Display text">
    Customize all displayed widget text elements, for example to modify button labels.

    <Frame background="subtle">
      ![Widget text contents](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4ad66ecae5df29e587afcf6e1898ccb41ca197abdaa2fde3ada4b10d256f8b7c/assets/images/conversational-ai/textcontents.gif)
    </Frame>
  </Tab>

  <Tab title="Terms">
    Display custom terms and conditions before the conversation.

    <Frame background="subtle">
      ![Terms setup](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/58dfd0abf92615f85c7314e8baec1bf4dd401cc88a04f1096baf817f05edb39d/assets/images/conversational-ai/terms-setup.png)
    </Frame>

    **Available options**

    * <strong>Terms content</strong>: Use Markdown to format your policy text.
    * <strong>Local storage key</strong>: A key (e.g., "terms\_accepted") to avoid prompting returning users.

    **Usage**

    The terms are displayed to users in a modal before starting the call:

    <Frame background="subtle">
      ![Terms display](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ca7511c60f1f6a29ee8bdd5c40083c73ef701f6cfd7ce1672161d73559a0c9b0/assets/images/conversational-ai/terms.png)
    </Frame>

    The terms can be written in Markdown, allowing you to:

    * Add links to external policies
    * Format text with headers and lists
    * Include emphasis and styling

    For more help with Markdown, see the [CommonMark help guide](https://commonmark.org/help/).

    <Info>
      Once accepted, the status is stored locally and the user won't be prompted again on subsequent
      visits.
    </Info>
  </Tab>

  <Tab title="Language">
    Enable multi-language support in the widget.

    ![Widget language](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/049e871eb0f609b071599e405c3da76351ee4ea38e52400fc416194930c42327/assets/images/conversational-ai/language.gif)

    <Note>
      To enable language selection, you must first [add additional
      languages](/docs/agents-platform/customization/voice/customization/language) to your agent.
    </Note>
  </Tab>

  <Tab title="Muting">
    Allow users to mute their audio in the widget.

    ![Widget's mute button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e6968e4ba057d98857fb41125bb57f92570ed7c49711ce423add1ea558de5919/assets/images/conversational-ai/widget-muted.png)

    To add the mute button please enable this in the `interface` card of the agent's `widget`
    settings.

    ![Widget's mute button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7db9df78926f3f3b3db7c286d4efc033356ec9b79cabe20670f65a52a624fae8/assets/images/conversational-ai/widget-mute-button.png)
  </Tab>

  <Tab title="Shareable page">
    Customize your public widget landing page (shareable link).

    <Frame background="subtle">
      ![Widget shareable page](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9d8b23aa816f4b7d727b3c0511ef91d046796bb57b8299382c53b6bcff746c50/assets/images/conversational-ai/widget-shareable-page.png)
    </Frame>

    **Available options**

    * <strong>Description</strong>: Provide a short paragraph explaining the purpose of the call.
  </Tab>
</Tabs>

***

## Advanced implementation

<Note>
  For more advanced customization, you should use the type-safe [ElevenAgents
  SDKs](/docs/developers/resources/libraries) with a Next.js, React, or Python application.
</Note>

### Client Tools

Client tools allow you to extend the functionality of the widget by adding event listeners. This enables the widget to perform actions such as:

* Redirecting the user to a specific page
* Sending an email to your support team
* Redirecting the user to an external URL

To see examples of these tools in action, start a call with the agent in the bottom right corner of this page. The [source code is available on GitHub](https://github.com/elevenlabs/elevenlabs-docs/blob/main/fern/assets/scripts/widget.js) for reference.

#### Creating a Client Tool

To create your first client tool, follow the [client tools guide](/docs/agents-platform/customization/tools/client-tools).

<Accordion title="Example: Creating the `redirectToExternalURL` Tool">
  <Frame background="subtle">
    ![Client tool configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d800b8c60cba2ab0a1d0aaaecc0652a678998a4161adaf10d83df51b928a7734/assets/images/conversational-ai/widget-client-tool-setup.png)
  </Frame>
</Accordion>

#### Example Implementation

Below is an example of how to handle the `redirectToExternalURL` tool triggered by the widget in your JavaScript code:

<CodeBlocks>
  ```javascript title="index.js"
  document.addEventListener('DOMContentLoaded', () => {
    const widget = document.querySelector('elevenlabs-convai');

    if (widget) {
      // Listen for the widget's "call" event to trigger client-side tools
      widget.addEventListener('elevenlabs-convai:call', (event) => {
        event.detail.config.clientTools = {
          // Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
          redirectToExternalURL: ({ url }) => {
            window.open(url, '_blank', 'noopener,noreferrer');
          },
        };
      });
    }
  });
  ```
</CodeBlocks>

<Info>
  Explore our type-safe [SDKs](/docs/developers/resources/libraries) for React, Next.js, and Python
  implementations.
</Info>


# SIP trunking

> Connect your existing phone system with ElevenLabs Agents using SIP trunking

## Overview

SIP (Session Initiation Protocol) trunking allows you to connect your existing telephony infrastructure directly to ElevenLabs Agents.
This integration enables all customers to use their existing phone systems while leveraging ElevenLabs' advanced voice AI capabilities.

With SIP trunking, you can:

* Connect your Private Branch Exchange (PBX) or SIP-enabled phone system to ElevenLabs' voice AI platform
* Route calls to AI agents without changing your existing phone infrastructure
* Handle both inbound and outbound calls
* Leverage encrypted TLS transport and media encryption for enhanced security

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/ivhBU4v_CPw?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Note>
  **Static IP SIP Servers**

  ElevenLabs offers SIP servers with static IP addresses for enterprise clients who require IP allowlisting for their security policies.

  Our static IP infrastructure uses a /24 IP address block containing 256 addresses distributed across multiple regions (US, EU, and India). You must allowlist the entire /24 block in your firewall configuration.

  For the default (US/International) environment, use `sip-static.rtc.elevenlabs.io` as your SIP endpoint. For isolated regions, use `sip-static.rtc.in.residency.elevenlabs.io` or `sip-static.rtc.eu.residency.elevenlabs.io` as needed. When using these endpoints, all traffic will originate exclusively from within that region. Specific whitelisting per-region is not available.

  This feature is available for Enterprise accounts and can also be enabled during Enterprise trials for testing purposes. To request access, [open a support ticket](https://help.elevenlabs.io/hc/en-us/requests/new?ticket_form_id=13145996177937) or contact your account representative. For more information, [contact sales](https://elevenlabs.io/contact-sales?utm_source=docs\&utm_medium=referral\&utm_campaign=static_ip_sip).
</Note>

## How SIP trunking works

SIP trunking establishes a direct connection between your telephony infrastructure and the ElevenLabs platform:

1. **Inbound calls**: Calls from your SIP trunk are routed to the ElevenLabs platform using your configured SIP INVITE address.
2. **Outbound calls**: Calls initiated by ElevenLabs are routed to your SIP trunk using your configured hostname, enabling your agents to make outgoing calls.
3. **Authentication**: Connection security for the signaling is maintained through either digest authentication (username/password) or Access Control List (ACL) authentication based on the signaling source IP.
4. **Signaling and Media**: The initial call setup (signaling) supports multiple transport protocols including TLS for encrypted communication. Once the call is established, the actual audio data (RTP stream) can be encrypted based on your media encryption settings.

## Making calls to ElevenLabs SIP trunk

When initiating calls to the ElevenLabs platform, you need to use the proper SIP URI format.

The ElevenLabs SIP trunk URI is:

```
sip:sip.rtc.elevenlabs.io:5060;transport=tcp
```

To make a call, construct a complete SIP URI that includes an identifier:

```
sip:+19991234567@sip.rtc.elevenlabs.io:5060
```

Where:

* `+19991234567` is the identifier (typically a phone number in E.164 format)
* The identifier can also be any string value, such as `1000` or `john`

<Warning>
  **Common Mistake**: Do not initiate calls directly to `sip@sip.rtc.elevenlabs.io:5060` without an
  identifier. The SIP URI must include a phone number or identifier after the `sip:` prefix and
  before the `@` symbol.
</Warning>

<Info>
  **SIP URI Format**: A [SIP URI](https://en.wikipedia.org/wiki/SIP_URI_scheme) follows the format
  `sip:identifier@domain:port` where the identifier is required to route the call properly.
</Info>

## Requirements

Before setting up SIP trunking, ensure you have:

1. A SIP-compatible PBX or telephony system
2. Phone numbers that you want to connect to ElevenLabs
3. Administrator access to your SIP trunk configuration
4. Appropriate firewall settings to allow SIP traffic
5. **TLS Support**: For enhanced security, ensure your SIP trunk provider supports TLS transport
6. **Audio codec compatibility**:
   Your system must support either G711 or G722 audio codecs or be capable of resampling audio on your end. ElevenLabs' SIP deployment outputs and receives audio at this sample rate. This is independent of any audio format configured on the agent for direct websocket connections.

## Setting up SIP trunking

<Steps>
  <Step title="Navigate to Phone Numbers">
    Go to the [Phone Numbers section](https://elevenlabs.io/app/agents/phone-numbers) in the ElevenLabs Agents dashboard.
  </Step>

  <Step title="Import SIP Trunk">
    Click on "Import a phone number from SIP trunk" button to open the configuration dialog.

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4c5f0192265d72a601768a6fa6ce6e11ebd8e115dc58e3b28460f5d0cdb7cabe/assets/images/conversational-ai/sip-trunk-select.png" alt="Select SIP trunk option" />
    </Frame>

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1f50bf163dee6de654322e84960d9e2f8c126a08aed6e90eba35692789ba2088/assets/images/conversational-ai/sip-trunk.png" alt="SIP trunk configuration dialog" />
    </Frame>
  </Step>

  <Step title="Enter basic configuration">
    Complete the basic configuration with the following information:

    * **Label**: A descriptive name for the phone number
    * **Phone Number**: The E.164 formatted phone number to connect (e.g., +15551234567)

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6ea0abfdeeafd24d8e4c480b935eacd25d63896a980b156a1420f362afa22650/assets/images/conversational-ai/sip-trunk-inbound.png" alt="SIP trunk basic configuration" />
    </Frame>
  </Step>

  <Step title="Configure transport and encryption">
    Configure the transport protocol and media encryption settings for enhanced security:

    * **Transport Type**: Select the transport protocol for SIP signaling:
      * **TCP**: Standard TCP transport
      * **TLS**: Encrypted TLS transport for enhanced security
    * **Media Encryption**: Configure encryption for RTP media streams:
      * **Disabled**: No media encryption
      * **Allowed**: Permits encrypted media streams
      * **Required**: Enforces encrypted media streams

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/bcb8c57349ba49644015853c1ff375e67700c27385034aec2eaf6f4df6fb1385/assets/images/conversational-ai/siptrunktls.png" alt="Select TLS or TCP transport" />
    </Frame>

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b8ab8b378bebe2c72ad3ea4fa84829a8d65a595558c95e2f464b47015d98be92/assets/images/conversational-ai/siptrunkmediaencryption.png" alt="Select media encryption setting" />
    </Frame>

    <Tip>
      **Security Best Practice**: Use TLS transport with Required media encryption for maximum security. This ensures both signaling and media are encrypted end-to-end.
    </Tip>
  </Step>

  <Step title="Configure outbound settings">
    Configure where ElevenLabs should send calls for your phone number:

    * **Address**: Hostname or IP address where the SIP INVITE is sent (e.g., `sip.telnyx.com`). This should be a hostname or IP address only, not a full SIP URI.
    * **Transport Type**: Select the transport protocol for SIP signaling:
      * **TCP**: Standard TCP transport
      * **TLS**: Encrypted TLS transport for enhanced security
    * **Media Encryption**: Configure encryption for RTP media streams:
      * **Disabled**: No media encryption
      * **Allowed**: Permits encrypted media streams
      * **Required**: Enforces encrypted media streams

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e544448d70847d436ce6071e384f4edd406d9048d4b8bb9d62e76862e55f2571/assets/images/conversational-ai/sip-outbound.png" alt="SIP trunk outbound configuration" />
    </Frame>

    <Tip>
      **Security Best Practice**: Use TLS transport with Required media encryption for maximum security. This ensures both signaling and media are encrypted end-to-end.
    </Tip>

    <Note>
      The **Address** field specifies where ElevenLabs will send outbound calls from your AI agents. Enter only the hostname or IP address without the `sip:` protocol prefix.
    </Note>
  </Step>

  <Step title="Add custom headers (optional)">
    If your SIP trunk provider requires specific headers for call routing or identification:

    * Click "Add Header" to add custom SIP headers
    * Enter the header name and value as required by your provider
    * You can add multiple headers as needed

    Custom headers are included with all outbound calls and can be used for:

    * Call routing and identification
    * Billing and tracking purposes
    * Provider-specific requirements
  </Step>

  <Step title="Configure authentication (optional)">
    Provide digest authentication credentials if required by your SIP trunk provider:

    * **SIP Trunk Username**: Username for SIP digest authentication
    * **SIP Trunk Password**: Password for SIP digest authentication

    If left empty, Access Control List (ACL) authentication will be used, which requires you to allowlist ElevenLabs IP addresses in your provider's settings.

    <Info>
      **Authentication Methods**:

      * **Digest Authentication**: Uses username/password credentials for secure authentication (recommended)
      * **ACL Authentication**: Uses IP address allowlisting for access control

      **Digest Authentication is strongly recommended** as it provides better security without relying on IP allowlisting, which can be complex to manage with dynamic IP addresses.
    </Info>
  </Step>

  <Step title="Complete Setup">
    Click "Import" to finalize the configuration.
  </Step>
</Steps>

## Client Data and Personalization

To ensure proper forwarding and traceability of call metadata, include the following custom SIP headers in your webhook payload and SIP INVITE request:

* **X-CALL-ID**: Unique identifier for the call
* **X-CALLER-ID**: Identifier for the calling party

These headers enable the system to associate call metadata with the conversation and provide context for personalization.

### Fallback Header Support

If the standard headers above are not present, the system will automatically look for the Twilio-specific SIP header:

* **sip.twilio.callSid**: Twilio's unique call identifier

This fallback ensures compatibility with Twilio's Elastic SIP Trunking without requiring configuration changes.

### Processing Flow

Once the relevant metadata is received through any of the supported headers, the `caller_id` and/or `call_id` are available in the [pre-call webhook](/docs/agents-platform/customization/personalization/twilio-personalization#how-it-works) and as [system dynamic variables](/docs/agents-platform/customization/personalization/dynamic-variables#system-dynamic-variables).

## Assigning Agents to Phone Numbers

After importing your SIP trunk phone number, you can assign it to a ElevenLabs agent:

1. Go to the Phone Numbers section in the ElevenAgents dashboard
2. Select your imported SIP trunk phone number
3. Click "Assign Agent"
4. Select the agent you want to handle calls to this number

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Issues">
    If you're experiencing connection problems:

    1. Verify your SIP trunk configuration on both the ElevenLabs side and your provider side
    2. Check that your firewall allows SIP signaling traffic on the configured transport protocol and port (5060 for TCP, 5061 for TLS) and ensure there is no whitelisting applied
    3. Confirm that your address hostname is correctly formatted and accessible
    4. Test with and without digest authentication credentials
    5. If using TLS transport, ensure your provider's TLS certificates are valid and properly configured
    6. Try different transport types (TCP only, as UDP is not currently available) to isolate TLS-specific issues

    **Important Network Architecture Information:**

    * ElevenLabs runs multiple SIP servers behind the load balancer `sip.rtc.elevenlabs.io`
    * The SIP servers communicate directly with your SIP server, bypassing the load balancer
    * SIP requests may come from different IP addresses due to our distributed infrastructure
    * If your security policy requires whitelisting inbound traffic, please contact our support team for assistance.
  </Accordion>

  <Accordion title="Authentication Failures">
    If calls are failing due to authentication issues:

    1. Double-check your SIP trunk username and password if using digest authentication
    2. Check your SIP trunk provider's logs for specific authentication error messages
    3. Verify that custom headers, if configured, match your provider's requirements
    4. Test with simplified configurations (no custom headers) to isolate authentication issues
  </Accordion>

  <Accordion title="TLS and Encryption Issues">
    If you're experiencing issues with TLS transport or media encryption:

    1. Verify that your SIP trunk provider supports TLS transport on port 5061
    2. Check certificate validity, expiration dates, and trust chains
    3. Ensure your provider supports SRTP media encryption if using "Required" media encryption
    4. Test with "Allowed" media encryption before using "Required" to isolate encryption issues
    5. Try TCP transport to isolate TLS-specific problems (UDP is not currently available)
    6. Contact your SIP trunk provider to confirm TLS and SRTP support
  </Accordion>

  <Accordion title="Custom Headers Issues">
    If you're having problems with custom headers:

    1. Verify the exact header names and values required by your provider
    2. Check for case sensitivity in header names
    3. Ensure header values don't contain special characters that need escaping
    4. Test without custom headers first, then add them incrementally
    5. Review your provider's documentation for supported custom headers
  </Accordion>

  <Accordion title="No Audio or One-Way Audio">
    If the call connects but there's no audio or audio only flows one way:

    1. Verify that your firewall allows UDP traffic for the RTP media stream (typically ports 10000-60000)
    2. Since RTP uses dynamic IP addresses, ensure firewall rules are not restricted to specific static IPs
    3. Check for Network Address Translation (NAT) issues that might be blocking the RTP stream
    4. If using "Required" media encryption, ensure both endpoints support SRTP
    5. Test with "Disabled" media encryption to isolate encryption-related audio issues
  </Accordion>

  <Accordion title="Audio Quality Issues">
    If you experience poor audio quality:

    1. Ensure your network has sufficient bandwidth (at least 100 Kbps per call) and low latency/jitter for UDP traffic
    2. Check for network congestion or packet loss, particularly on the UDP path
    3. Verify codec settings match on both ends
    4. If using media encryption, ensure both endpoints efficiently handle SRTP processing
    5. Test with different media encryption settings to isolate quality issues
  </Accordion>

  <Accordion title="Call not disconnecting after sending the BYE request (receiving a 481 response)">
    A 481 response on a BYE usually means the request reached a SIP server that does not have the dialog state for the call.
    This often happens when the initial TCP connection has already closed and the BYE is re-sent to the generic load balancer address (for example `sip.rtc.elevenlabs.io`)
    rather than the specific `Contact` URI returned in the 200 OK response.

    1. When re-establishing a TCP connection for BYE, always target the `Contact` address from the INVITE response so the request reaches the same SIP server that handled the dialog.
    2. Avoid sending BYE to the load balancer URI because the request can land on a different SIP node, which rejects it with 481.

    <Note>
      See <a href="https://datatracker.ietf.org/doc/html/rfc3261#section-8.1.1.8">RFC 3261 Section 8.1.1.8</a> for the normative behavior governing Contact headers and dialog routing.
    </Note>
  </Accordion>
</AccordionGroup>

## Limitations and Considerations

* Support for multiple concurrent calls depends on your subscription tier
* Call recording and analytics features are available but may require additional configuration
* Outbound calling capabilities may be limited by your SIP trunk provider
* **TLS Support**: Ensure your SIP trunk provider supports TLS 1.2 or higher for encrypted transport
* **Media Encryption**: SRTP support varies by provider; verify compatibility before requiring encryption
* **Audio format**: ElevenLabs' SIP deployment outputs and receives audio in G711 8kHz or G722 16kHz audio codecs. This is independent of any audio format configured on the agent for direct websocket connections. Your SIP trunk system must either support this format natively or perform resampling to match your system's requirements

## FAQ

<AccordionGroup>
  <Accordion title="Can I use my existing phone numbers with ElevenLabs?">
    Yes, SIP trunking allows you to connect your existing phone numbers directly to ElevenLabs'
    ElevenAgents without porting them.
  </Accordion>

  <Accordion title="What SIP trunk providers are compatible with ElevenLabs?">
    ElevenLabs is compatible with most standard SIP trunk providers including Twilio, Vonage,
    RingCentral, Sinch, Infobip, Telnyx, Exotel, Plivo, Bandwidth, and others that support SIP
    protocol standards. TLS transport and SRTP media encryption are supported for enhanced security.
  </Accordion>

  <Accordion title="Should I use TLS transport for better security?">
    Yes, TLS transport is highly recommended for production environments. It provides encrypted SIP
    signaling which enhances security for your calls. Combined with required media encryption, it
    ensures comprehensive protection of your communications. Always verify your SIP trunk provider
    supports TLS before enabling it.
  </Accordion>

  <Accordion title="What's the difference between transport types?">
    * **TCP**: Reliable but unencrypted signaling - **TLS**: Encrypted and reliable signaling
      (recommended for production)

    <Note>
      UDP transport is not currently available. For security-critical applications, always use TLS
      transport.
    </Note>
  </Accordion>

  <Accordion title="What are custom headers used for?">
    Custom SIP headers allow you to include provider-specific information with outbound calls. Common
    uses include call routing, billing codes, caller identification, and meeting specific provider
    requirements.
  </Accordion>

  <Accordion title="How many concurrent calls are supported?">
    The number of concurrent calls depends on your subscription plan. Enterprise plans typically allow
    for higher volumes of concurrent calls.
  </Accordion>

  <Accordion title="Can I route calls conditionally to different agents?">
    Yes, you can use your existing PBX system's routing rules to direct calls to different phone
    numbers, each connected to different ElevenLabs agents.
  </Accordion>

  <Accordion title="Do I need to match the leading + format when importing phone numbers?">
    Yes, the phone number format must be consistent between your SIP URI and your imported phone number configuration. If you call the SIP URI with a leading + (e.g., `sip:+19991234567@sip.rtc.elevenlabs.io:5060`), you must also import the phone number with the leading + (e.g., `+19991234567`). Similarly, if you call without the leading +, import the phone number without it. Mismatched formats will prevent proper call routing.
  </Accordion>
</AccordionGroup>

## Next steps

* [Learn about creating ElevenLabs agents](/docs/agents-platform/quickstart)


# Twilio native integration

> Learn how to configure inbound calls for your agent with Twilio.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/1_ebl-acp6M?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

This guide shows you how to connect a Twilio phone number to your ElevenLabs agent to handle both inbound and outbound calls.

You will learn to:

* Import an existing Twilio phone number.
* Link it to your agent to handle inbound calls.
* Initiate outbound calls using your agent.

## Phone Number Types & Capabilities

ElevenLabs supports two types of Twilio phone numbers with different capabilities:

### Purchased Twilio Numbers (Full Support)

* **Inbound calls**: Supported - Can receive calls and route them to agents
* **Outbound calls**: Supported - Can make calls using agents
* **Requirements**: Number must be purchased through Twilio and appear in your "Phone Numbers" section

### Verified Caller IDs (Outbound Only)

* **Inbound calls**: Not supported - Cannot receive calls or be assigned to agents
* **Outbound calls**: Supported - Can make calls using agents
* **Requirements**: Number must be verified in Twilio's "Verified Caller IDs" section
* **Use case**: Ideal for using your existing business number for outbound AI calls

Learn more about [verifying caller IDs at scale](https://www.twilio.com/docs/voice/api/verifying-caller-ids-scale) in Twilio's documentation.

<Note>
  During phone number import, ElevenLabs automatically detects the capabilities of your number based
  on its configuration in Twilio.
</Note>

## Guide

### Prerequisites

* A [Twilio account](https://twilio.com/).
* Either:
  * A purchased & provisioned Twilio [phone number](https://www.twilio.com/docs/phone-numbers) (for inbound + outbound)
  * OR a [verified caller ID](https://www.twilio.com/docs/voice/make-calls#verify-your-caller-id) in Twilio (for outbound only)

<Steps>
  <Step title="Import a Twilio phone number">
    In the ElevenAgents dashboard, go to the [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers) tab.

    <Frame background="subtle">
      ![ElevenAgents phone numbers page](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7efb681147acd8f04803f84ed7f3289f0e90eb1fb0173e2a825836408cee89d1/assets/images/conversational-ai/phone-numbers-page.png)
    </Frame>

    Next, fill in the following details:

    * **Label:** A descriptive name (e.g., `Customer Support Line`).
    * **Phone Number:** The Twilio number you want to use.
    * **Twilio SID:** Your Twilio Account SID.
    * **Twilio Token:** Your Twilio Auth Token.

    <Note>
      You can find your account SID and auth token [**in the Twilio admin console**](https://www.twilio.com/console).
    </Note>

    <Tabs>
      <Tab title="ElevenAgents dashboard">
        <Frame background="subtle">
          ![Phone number configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9501110d58bfeca27cb9983bc44035864504bdc2ed9c78d9decbd04802f64418/assets/images/conversational-ai/phone-numbers-new.png)
        </Frame>
      </Tab>

      <Tab title="Twilio admin console">
        Copy the Twilio SID and Auth Token from the [Twilio admin
        console](https://www.twilio.com/console).

        <Frame background="subtle">
          ![Phone number details](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/42da512d1cdfb4ca4504c3162fecfed108580d9488236a0cc6a4a1d23a19da14/assets/images/conversational-ai/twilio-settings.png)
        </Frame>
      </Tab>
    </Tabs>

    <Note>
      ElevenLabs automatically configures the Twilio phone number with the correct settings.
    </Note>

    <Accordion title="Applied settings">
      <Frame background="subtle">
        ![Twilio phone number configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b11d57a0aa588964bbd0117d2135c55592569a4bf051f00f17aa3ee632833a47/assets/images/conversational-ai/twilio-configuration.png)
      </Frame>
    </Accordion>

    <Info>
      **Phone Number Detection**: ElevenLabs will automatically detect whether your number supports:

      * **Inbound + Outbound**: Numbers purchased through Twilio
      * **Outbound Only**: Numbers verified as caller IDs in Twilio

      If your number is not found in either category, you'll receive an error asking you to verify it exists in your Twilio account.
    </Info>
  </Step>

  <Step title="Assign your agent (Inbound-capable numbers only)">
    If your phone number supports inbound calls, you can assign an agent to handle incoming calls.

    <Frame background="subtle">
      ![Select agent for inbound calls](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b85c122ef8607527041516e789b0a19047cbf85a13cd3237ee5a7670683815a7/assets/images/conversational-ai/twilio-assigned-agent.png)
    </Frame>

    <Note>
      Numbers that only support outbound calls (verified caller IDs) cannot be assigned to agents and
      will show as disabled in the agent dropdown.
    </Note>
  </Step>
</Steps>

Test the agent by giving the phone number a call. Your agent is now ready to handle inbound calls and engage with your customers.

<Tip>
  Monitor your first few calls in the [Calls History
  dashboard](https://elevenlabs.io/app/agents/history) to ensure everything is working as expected.
</Tip>

## Making Outbound Calls

<Info>
  Both purchased Twilio numbers and verified caller IDs can be used for outbound calls. The outbound
  call button will be disabled for numbers that don't support outbound calling.
</Info>

Your imported Twilio phone number can also be used to initiate outbound calls where your agent calls a specified phone number.

<Steps>
  <Step title="Initiate an outbound call">
    From the [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers) tab, locate your imported Twilio number and click the **Outbound call** button.

    <Frame background="subtle">
      ![Outbound call button](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/953a870b0ab0c0aa30872b3692260f0879f390d4b4b83c7f82e816385504034f/assets/images/conversational-ai/outbound-button.png)
    </Frame>
  </Step>

  <Step title="Configure the call">
    In the Outbound Call modal:

    1. Select the agent that will handle the conversation
    2. Enter the phone number you want to call
    3. Click **Send Test Call** to initiate the call

    <Frame background="subtle">
      ![Outbound call configuration](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f6b01412a68217661028e6924ce90089bdd5eaa693c8aeafbc321c632de921b7/assets/images/conversational-ai/outbound-modal.png)
    </Frame>
  </Step>
</Steps>

Once initiated, the recipient will receive a call from your Twilio number. When they answer, your agent will begin the conversation.

<Tip>
  Outbound calls appear in your [Calls History dashboard](https://elevenlabs.io/app/agents/history)
  alongside inbound calls, allowing you to review all conversations.
</Tip>

<Note>
  When making outbound calls, your agent will be the initiator of the conversation, so ensure your
  agent has appropriate initial messages configured to start the conversation effectively.
</Note>


# Twilio regional routing

> Configure regional routing for Twilio phone numbers to ensure data residency compliance.

## Overview

Regional routing ensures that your telephony data stays within a specific geographic region. When using Twilio with ElevenLabs in an isolated environment (such as EU residency), you must configure regional routing correctly to maintain data residency compliance.

This guide explains what regional routing is, why it matters, and how to configure it properly in both Twilio and ElevenLabs.

## What is regional routing?

Regional routing is Twilio's mechanism for ensuring that call data is processed and stored within a specific geographic region. Think of it as data residency for your telephony infrastructure.

<Note>
  By default, Twilio phone numbers are configured to route through the US region (`us1`), **even if
  the phone number itself is from another country**. For example, an Italian phone number will still
  route through the US unless regional routing is explicitly configured.
</Note>

## Why regional routing matters

When using ElevenLabs in an isolated environment (such as EU residency), all data processing must remain within your designated region. Without proper regional routing configuration:

* **Data residency violations**: Call data may be routed through unintended regions
* **Failed API operations**: Operations on ongoing calls (such as transfers, hold, resume) will fail
* **SDK routing mismatches**: The Twilio SDK defaults to the `us1` region, causing API calls to be sent to the wrong region even when Twilio has routed the call correctly on the backend

## How it works

When you import a Twilio phone number into ElevenLabs:

1. **Twilio routes the call**: Twilio automatically routes incoming calls to the region configured in your Twilio account (this can be `us1`, `ie1` for Ireland, `au1` for Australia, etc.)
2. **ElevenLabs needs to know the region**: To perform operations on ongoing calls (like transfers), ElevenLabs must send API requests to the same region where Twilio routed the call
3. **Region specification prevents failures**: By specifying the routing region in the ElevenLabs platform, we ensure all API calls target the correct Twilio region

<Warning>
  If the routing region is not specified or is incorrect, operations like call transfers will fail
  because the API requests will be sent to the default `us1` region while the actual call is being
  handled in a different region.
</Warning>

## Configuration

<Steps>
  ### Check your Twilio regional routing

  First, verify which region your Twilio phone number is configured to use:

  1. Log into your [Twilio Console](https://console.twilio.com/)
  2. Navigate to **Phone Numbers** → **Manage** → **Active numbers**
  3. Select your phone number
  4. Look for the **Voice & Fax** configuration section
  5. Check the **Regional routing** or **Edge Location** setting

  Common Twilio regions:

  * `us1` - United States (default)
  * `ie1` - Ireland (Europe)
  * `au1` - Australia
  * `br1` - Brazil
  * `jp1` - Japan
  * `sg1` - Singapore

  <Tip>
    If you're using an isolated environment (like EU residency), ensure your Twilio numbers are
    configured to route through the matching region (e.g., `ie1` for EU).
  </Tip>

  ### Configure regional routing in Twilio

  If your phone number is not configured for the correct region:

  1. In the [Twilio Console](https://console.twilio.com/), go to your phone number configuration
  2. Find the **Voice & Fax** section
  3. Set the **Edge Location** to match your desired region
  4. Save the configuration

  <Note>
    Regional routing configuration in Twilio may require additional setup or account permissions.
    Contact [Twilio Support](https://support.twilio.com/) if you need assistance enabling regional
    routing for your account.
  </Note>

  ### Specify the routing region in ElevenLabs

  When you import or configure a Twilio phone number in the ElevenLabs [Phone Numbers](https://elevenlabs.io/app/agents/phone-numbers) page:

  1. Navigate to the phone number configuration
  2. If you're using an isolated environment, you'll see a warning message that reads: "You are using a phone number in an isolated environment. Double check the routing region for this phone number in your provider."
  3. Verify that the **routing region** matches your Twilio configuration
  4. Ensure the region specified matches the region configured in your Twilio account
     <Warning>
       If you're using regional routing, you must use a **regional API key** from Twilio that
       corresponds to your routing region. Your standard US API key will not work for non-US regions
       and will result in authentication errors. Generate a region-specific API key in your [Twilio
       Console](https://console.twilio.com/).
     </Warning>
</Steps>

## Verifying your configuration

To verify that regional routing is configured correctly:

1. **Check Twilio Console**: Confirm your phone number shows the correct Edge Location
2. **Check ElevenLabs Platform**: Verify the routing region setting matches your Twilio configuration
3. **Test call operations**: Make a test call and verify that operations like call transfer work correctly

<Tip>
  Monitor your first few calls in the [Calls History
  dashboard](https://elevenlabs.io/app/agents/history) after configuring regional routing to ensure
  everything works as expected.
</Tip>

## Common issues

<AccordionGroup>
  <Accordion title="Call transfers are failing">
    This typically indicates a regional routing mismatch. Verify that:

    * Your Twilio phone number is configured with the correct Edge Location
    * The routing region specified in ElevenLabs matches your Twilio configuration
    * You're using an isolated environment that matches the routing region
  </Accordion>

  <Accordion title="My phone number is from Europe but routing through US">
    The phone number's geographic origin doesn't determine routing behavior. You must explicitly
    configure regional routing in Twilio. By default, all numbers (including European numbers) route
    through `us1` unless configured otherwise.
  </Accordion>

  <Accordion title="I'm not using an isolated environment - do I need this?">
    If you're using the standard ElevenLabs environment (not EU residency or another isolated
    environment), regional routing configuration is optional.
  </Accordion>

  <Accordion title="How do I know which region to use?">
    Choose a region that:

    * Matches your data residency requirements (e.g., `ie1` for EU data residency)
    * Is closest to your users for optimal latency
    * Matches your ElevenLabs isolated environment (if applicable)
  </Accordion>

  <Accordion title="I'm getting authentication errors with my Twilio credentials">
    If you're seeing authentication errors when using regional routing, verify that you're using the correct **regional API key**:

    * Regional routing requires a region-specific API key from Twilio, not your standard US API key
    * Generate a new API key scoped to your target region (e.g., `ie1`, `au1`) in the Twilio Console
    * Update your credentials in ElevenLabs with the regional API key
    * Your Account SID remains the same, but the API key must match the region
  </Accordion>
</AccordionGroup>

## Best practices

* **Match regions**: Ensure your Twilio regional routing matches your ElevenLabs environment
* **Document configuration**: Keep records of which numbers use which regions
* **Test thoroughly**: Verify call operations work correctly after changing regional routing
* **Monitor calls**: Watch for failures in the Calls History dashboard that might indicate routing issues
* **Plan for scale**: If you plan to expand to new regions, consider regional routing from the start

## Additional resources

* [Twilio Regional Routing Documentation](https://www.twilio.com/docs/global-infrastructure/edge-locations)
* [ElevenLabs Data Residency Guide](/docs/overview/administration/data-residency)
* [Twilio Phone Numbers Guide](/docs/agents-platform/phone-numbers/twilio-integration/native-integration)


# Register Twilio calls

> Use your own Twilio infrastructure to connect calls to ElevenLabs agents.

<Warning title="Advanced">
  This guide covers an advanced integration pattern for developers who need full control over their
  Twilio infrastructure. For a simpler setup, consider using the [native Twilio
  integration](/docs/agents-platform/phone-numbers/twilio-integration/native-integration) which
  handles configuration automatically.
</Warning>

## When to use each approach

Before diving in, understand the trade-offs between the native integration and the register call approach:

| Feature                 | Native integration | Register call  |
| ----------------------- | ------------------ | -------------- |
| Ease of setup           | Easier             | More complex   |
| Call transfers          | Supported          | Not supported  |
| Custom Twilio logic     | Limited            | Full control   |
| Phone number management | Through ElevenLabs | Through Twilio |

## Overview

The register call endpoint allows you to use your own Twilio infrastructure while leveraging ElevenLabs agents for the conversation. Instead of importing your Twilio number into ElevenLabs, you maintain full control of your Twilio setup and use the ElevenLabs API to register calls and receive [TwiML](https://www.twilio.com/docs/voice/twiml) for connecting them to your agents.

This approach is ideal when you:

* Need to maintain your existing Twilio infrastructure and workflows
* Want programmatic control over call routing and handling
* Have complex call flows that require custom Twilio logic before connecting to an agent
* Need to integrate ElevenLabs agents into an existing telephony system

## How it works

1. Your server receives an inbound call or initiates an outbound call via Twilio
2. Your server calls the ElevenLabs register call endpoint with agent and call details
3. ElevenLabs returns TwiML that connects the call to your agent via WebSocket
4. You return this TwiML to Twilio to establish the connection

<Note>
  When using the register call endpoint, call transfer functionality is not available as ElevenLabs
  does not have direct access to your Twilio account credentials.
</Note>

## Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs Conversational Agent ([create one here](/docs/agents-platform/quickstart))
* A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number
* Your agent configured with μ-law 8000 Hz audio format (see [agent configuration](#agent-configuration))

## Agent configuration

Before using the register call endpoint, configure your agent to use the correct audio format supported by Twilio.

<Steps>
  <Step title="Configure TTS Output">
    1. Navigate to your agent settings
    2. Go to the Voice section
    3. Select "μ-law 8000 Hz" from the dropdown

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b37196c36051755fb0b10a99b393501ec11573f963c83b6b092e1b5926c6617f/assets/images/conversational-ai/twilio-1.png)
    </Frame>
  </Step>

  <Step title="Set Input Format">
    1. Navigate to your agent settings
    2. Go to the Advanced section
    3. Select "μ-law 8000 Hz" for the input format

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ec87531c38e26f2293b90126f1b91ee9acb4cc677c6f3e83a6e1b6029743d3f7/assets/images/conversational-ai/twilio-2.png)
    </Frame>
  </Step>
</Steps>

## API reference

The register call endpoint accepts the following parameters:

| Parameter                             | Type   | Required | Description                                       |
| ------------------------------------- | ------ | -------- | ------------------------------------------------- |
| `agent_id`                            | string | Yes      | The ID of the agent to handle the call            |
| `from_number`                         | string | Yes      | The caller's phone number                         |
| `to_number`                           | string | Yes      | The destination phone number                      |
| `direction`                           | string | No       | Call direction: `inbound` (default) or `outbound` |
| `conversation_initiation_client_data` | object | No       | Dynamic variables and configuration overrides     |

The endpoint returns TwiML that you should pass directly to Twilio.

## Implementation

<CodeBlocks>
  ```python
  import os
  from fastapi import FastAPI, Request
  from fastapi.responses import Response
  from elevenlabs import ElevenLabs

  app = FastAPI()

  elevenlabs = ElevenLabs()
  AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")

  @app.post("/twilio/inbound")
  async def handle_inbound_call(request: Request):
      form_data = await request.form()
      from_number = form_data.get("From")
      to_number = form_data.get("To")

      # Register the call with ElevenLabs
      twiml = elevenlabs.conversational_ai.twilio.register_call(
          agent_id=AGENT_ID,
          from_number=from_number,
          to_number=to_number,
          direction="inbound",
          conversation_initiation_client_data={
              "dynamic_variables": {
                  "caller_number": from_number,
              }
          }
      )

      # Return the TwiML directly to Twilio
      return Response(content=twiml, media_type="application/xml")

  if __name__ == "__main__":
      import uvicorn
      uvicorn.run(app, host="0.0.0.0", port=8000)
  ```

  ```typescript
  import { ElevenLabsClient } from 'elevenlabs';
  import express from 'express';

  const app = express();
  app.use(express.urlencoded({ extended: true }));

  const elevenlabs = new ElevenLabsClient();
  const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

  // Handle incoming Twilio calls
  app.post('/twilio/inbound', async (req, res) => {
    const { From: fromNumber, To: toNumber } = req.body;

    // Register the call with ElevenLabs
    const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
      agentId: AGENT_ID,
      fromNumber,
      toNumber,
      direction: 'inbound',
      conversationInitiationClientData: {
        dynamicVariables: {
          caller_number: fromNumber,
        },
      },
    });

    // Return the TwiML directly to Twilio
    res.type('application/xml').send(twiml);
  });

  app.listen(8000, () => {
    console.log('Server running on port 8000');
  });
  ```
</CodeBlocks>

## Outbound calls

For outbound calls, initiate the call through Twilio and point the webhook URL to your server, which then registers with ElevenLabs:

<CodeBlocks>
  ```python
  from twilio.rest import Client
  import os
  from fastapi import Request
  from fastapi.responses import Response
  from elevenlabs import ElevenLabs

  # Initialize clients
  twilio_client = Client(
      os.getenv("TWILIO_ACCOUNT_SID"),
      os.getenv("TWILIO_AUTH_TOKEN")
  )
  elevenlabs = ElevenLabs()
  AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")

  def initiate_outbound_call(to_number: str):
      call = twilio_client.calls.create(
          from_=os.getenv("TWILIO_PHONE_NUMBER"),
          to=to_number,
          url="https://your-server.com/twilio/outbound"
      )
      return call.sid

  @app.post("/twilio/outbound")
  async def handle_outbound_webhook(request: Request):
      form_data = await request.form()
      from_number = form_data.get("From")
      to_number = form_data.get("To")

      twiml = elevenlabs.conversational_ai.twilio.register_call(
          agent_id=AGENT_ID,
          from_number=from_number,
          to_number=to_number,
          direction="outbound",
      )

      return Response(content=twiml, media_type="application/xml")
  ```

  ```typescript
  import { ElevenLabsClient } from 'elevenlabs';
  import Twilio from 'twilio';

  // Initialize clients
  const twilioClient = new Twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
  const elevenlabs = new ElevenLabsClient();
  const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

  // Initiate an outbound call
  async function initiateOutboundCall(toNumber: string) {
    const call = await twilioClient.calls.create({
      from: process.env.TWILIO_PHONE_NUMBER,
      to: toNumber,
      url: 'https://your-server.com/twilio/outbound',
    });
    return call.sid;
  }

  // Handle the Twilio webhook for outbound calls
  app.post('/twilio/outbound', async (req, res) => {
    const { From: fromNumber, To: toNumber } = req.body;

    const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
      agentId: AGENT_ID,
      fromNumber,
      toNumber,
      direction: 'outbound',
    });

    res.type('application/xml').send(twiml);
  });
  ```
</CodeBlocks>

## Personalizing conversations

Use the `conversation_initiation_client_data` parameter to pass dynamic variables and override agent configuration:

```json
{
  "agent_id": "your-agent-id",
  "from_number": "+1234567890",
  "to_number": "+0987654321",
  "direction": "inbound",
  "conversation_initiation_client_data": {
    "dynamic_variables": {
      "customer_name": "John Doe",
      "account_type": "premium",
      "order_id": "ORD-12345"
    }
  }
}
```

<Info>
  For more information about dynamic variables and overrides, see the [dynamic
  variables](/docs/agents-platform/customization/personalization/dynamic-variables) and
  [overrides](/docs/agents-platform/customization/personalization/overrides) documentation.
</Info>

## Twilio configuration

Configure your Twilio phone number to point to your server:

<Steps>
  <Step title="Create a public URL">
    For local development, use [ngrok](https://ngrok.com) to expose your server:

    ```bash
    ngrok http 8000
    ```
  </Step>

  <Step title="Configure your Twilio number">
    1. Go to the [Twilio Console](https://console.twilio.com)
    2. Navigate to Phone Numbers > Manage > Active numbers
    3. Select your phone number
    4. Under "Voice Configuration", set the webhook URL to your server endpoint (e.g., `https://your-ngrok-url.ngrok.app/twilio/inbound`)
    5. Set the HTTP method to POST

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/510d09d492b0c6ac9966f8fe39a9da685df79e8108f6fbc55fe502f48f650084/assets/images/conversational-ai/twilio-4.png)
    </Frame>
  </Step>
</Steps>

## Limitations

When using the register call endpoint instead of the native integration:

* **No call transfers**: Transfer functionality is not available as ElevenLabs does not have access to your Twilio credentials
* **Manual configuration**: You must configure audio formats and handle TwiML routing yourself
* **No dashboard import**: Phone numbers registered this way do not appear in the ElevenLabs phone numbers dashboard


# Vonage integration

> Integrate ElevenAgents with Vonage voice calls using a WebSocket connector.

## Overview

Connect ElevenLabs Agents to Vonage Voice API or Video API calls using a [WebSocket connector application](https://github.com/nexmo-se/elevenlabs-agent-ws-connector). This enables real-time, bi-directional audio streaming for use cases like PSTN calls, SIP trunks, and WebRTC clients.

## How it works

The Node.js connector bridges Vonage and ElevenLabs:

1. Vonage initiates a WebSocket connection to the connector for an active call.
2. The connector establishes a WebSocket connection to the ElevenLabs Agents endpoint.
3. Audio is relayed: Vonage (L16) -> Connector -> ElevenLabs (base64) and vice-versa.
4. The connector manages conversation events (`user_transcript`, `agent_response`, `interruption`).

## Setup

<Steps>
  ### 1. Get ElevenLabs credentials

  * **API Key**: API keys are located in the [API Keys tab on the Developers page](https://elevenlabs.io/app/developers) which can be found linked in the sidebar.
  * **Agent ID**: Find the agent in the [ElevenAgents dashboard](https://elevenlabs.io/app/agents/agents/). Once you have selected the agent click on the settings button and select "Copy Agent ID".

  ### 2. Configure the connector

  Clone the repository and set up the environment file.

  ```bash
  git clone https://github.com/nexmo-se/elevenlabs-agent-ws-connector.git
  cd elevenlabs-agent-ws-connector
  cp .env.example .env
  ```

  Add your credentials to `.env`:

  ```bash title=".env"
  ELEVENLABS_API_KEY = YOUR_API_KEY;
  ELEVENLABS_AGENT_ID = YOUR_AGENT_ID;
  ```

  Install dependencies: `npm install`.

  ### 3. Expose the connector (local development)

  Use ngrok, or a similar service, to create a public URL for the connector (default port 6000).

  ```bash
  ngrok http 6000
  ```

  Note the public `Forwarding` URL (e.g., `xxxxxxxx.ngrok-free.app`). **Do not include `https://`** when configuring Vonage.

  ### 4. Run the connector

  Start the application:

  ```bash
  node elevenlabs-agent-ws-connector.cjs
  ```

  ### 5. Configure Vonage voice application

  Your Vonage app needs to connect to the connector's WebSocket endpoint (`wss://YOUR_CONNECTOR_HOSTNAME/socket`). This is the ngrok URL from step 3.

  * **Use Sample App**: Configure the [sample Vonage app](https://github.com/nexmo-se/voice-to-ai-engines) with `PROCESSOR_SERVER` set to your connector's hostname.
  * **Update Existing App**: Modify your [Nexmo Call Control Object](https://developer.vonage.com/en/voice/voice-api/ncco-reference) to include a `connect` action targeting the connector's WebSocket URI (`wss://...`) with `content-type: audio/l16;rate=16000`. Pass necessary query parameters like `peer_uuid` and `webhook_url`.

  ### 6. Test

  Make an inbound or outbound call via your Vonage application to interact with the ElevenLabs agent.
</Steps>

## Cloud deployment

For production, deploy the connector to a stable hosting provider (e.g., Vonage Cloud Runtime) with a public hostname.


# Telnyx SIP trunking

> Connect Telnyx SIP trunks with ElevenLabs Agents.

<Note>
  Before following this guide, consider reading the [SIP trunking
  guide](/docs/agents-platform/phone-numbers/sip-trunking) to understand how ElevenLabs supports SIP
  trunks.
</Note>

## Overview

This guide explains how to connect your Telnyx SIP trunks directly to ElevenLabs Agents. This integration allows you to use your existing Telnyx phone numbers and infrastructure while leveraging ElevenLabs' advanced voice AI capabilities.

## How SIP trunking with Telnyx works

SIP trunking establishes a direct connection between your Telnyx telephony infrastructure and the ElevenLabs platform:

1. **Inbound calls**: Calls from your Telnyx SIP trunk are routed to the ElevenLabs platform using our origination URI. You will configure this in your Telnyx account.
2. **Outbound calls**: Calls initiated by ElevenLabs are routed to your Telnyx SIP trunk using your termination URI, enabling your agents to make outgoing calls.
3. **Authentication**: Connection security is maintained through either digest authentication (username/password) or Access Control List (ACL) authentication.
4. **Signaling and Media**: The initial call setup (signaling) uses TCP. Once the call is established, the actual audio data (RTP stream) is transmitted over UDP.

## Requirements

Before setting up the Telnyx SIP trunk integration, ensure you have:

1. An active ElevenLabs account
2. An active Telnyx account
3. At least one phone number purchased or ported into your Telnyx account
4. Administrator access to your Telnyx portal
5. Appropriate firewall settings to allow SIP and RTP traffic

## Creating a SIP trunk using the Telnyx UI

<Steps>
  <Step title="Sign in to Telnyx">
    Log in to your Telnyx account at [portal.telnyx.com](https://portal.telnyx.com/).
  </Step>

  <Step title="Purchase a phone number">
    Navigate to the Numbers section and purchase a phone number that will be used with your ElevenLabs agent.
  </Step>

  <Step title="Navigate to SIP Trunking">
    Go to Voice » [SIP Trunking](https://portal.telnyx.com/#/voice/connections) in the Telnyx portal.
  </Step>

  <Step title="Create a SIP connection">
    Click on Create SIP Connection and choose FQDN as the connection type, then save.
  </Step>

  <Step title="Configure authentication">
    1. In the Authentication & Routing Configuration section, select Outbound Calls Authentication.
    2. In the Authentication Method field, select Credentials and enter a username and password.
    3. Select Add FQDN and enter `sip.rtc.elevenlabs.io` into the FQDN field.
  </Step>

  <Step title="Configure inbound settings">
    1. Select the Inbound tab.
    2. In the Destination Number Format field, select `+E.164`.
    3. For SIP Transport Protocol, select TCP.
    4. In the SIP Region field, select your region.
  </Step>

  <Step title="Configure outbound settings">
    1. Select the Outbound tab.
    2. In the Outbound Voice Profile field, select or create an outbound voice profile.
  </Step>

  <Step title="Assign phone number">
    1. Select the Numbers tab.
    2. Assign your purchased phone number to this SIP connection.
  </Step>
</Steps>

<Warning>
  After setting up your Telnyx SIP trunk, follow the [SIP trunking
  guide](/docs/agents-platform/phone-numbers/sip-trunking) to complete the configuration in
  ElevenLabs.
</Warning>


# Plivo

> Integrate ElevenLabs Agents with your Plivo SIP trunks

<Note>
  Before following this guide, consider reading the [SIP trunking
  guide](/docs/agents-platform/phone-numbers/sip-trunking) to understand how ElevenLabs supports SIP
  trunks.
</Note>

## Overview

This guide explains how to connect your Plivo SIP trunks directly to ElevenLabs Agents.
This integration allows you to use your existing Plivo phone numbers and infrastructure while leveraging ElevenLabs' advanced voice AI capabilities, for both inbound and outbound calls.

## How SIP trunking with Plivo works

SIP trunking establishes a direct connection between your Plivo telephony infrastructure and the ElevenLabs platform:

1. **Inbound calls**: Calls from your Plivo SIP trunk are routed to the ElevenLabs platform using our origination URI. You will configure this in your Plivo account.
2. **Outbound calls**: Calls initiated by ElevenLabs are routed to your Plivo SIP trunk using your termination URI, enabling your agents to make outgoing calls.
3. **Authentication**: Connection security for the signaling is maintained through either digest authentication (username/password) or Access Control List (ACL) authentication based on the signaling source IP from Plivo.
4. **Signaling and Media**: The initial call setup (signaling) uses TCP. Once the call is established, the actual audio data (RTP stream) is transmitted over UDP.

## Requirements

Before setting up the Plivo SIP trunk integration, ensure you have:

1. An active Plivo account with SIP trunking enabled
2. Plivo phone numbers that you want to connect to ElevenLabs
3. Administrator access to your Plivo account and SIP trunk configuration
4. Appropriate firewall settings to allow SIP traffic to and from ElevenLabs and Plivo

## Configuring Plivo SIP trunks

This section provides detailed instructions for creating SIP trunks in Plivo before connecting them to ElevenLabs.

### Setting up inbound trunks (calls from Plivo to ElevenLabs)

<Steps>
  <Step title="Access Plivo Console">
    Sign in to the Plivo Console.
  </Step>

  <Step title="Navigate to Zentrunk Dashboard">
    Go to the Zentrunk Dashboard in your Plivo account.
  </Step>

  <Step title="Create inbound SIP trunk">
    1. Select "Create New Inbound Trunk" and provide a descriptive name for your trunk.
    2. Under Trunk Authentication, click "Add New URI".
    3. Enter the ElevenLabs SIP URI: `sip.rtc.elevenlabs.io`
    4. Select "Create Trunk" to complete your inbound trunk creation.
  </Step>

  <Step title="Assign phone number to trunk">
    1. Navigate to the Phone Numbers Dashboard and select the number you want to route to your inbound trunk.
    2. Under Number Configuration, set "Trunk" to your newly created inbound trunk.
    3. Select "Update" to save the configuration.
  </Step>
</Steps>

### Setting up outbound trunks (calls from ElevenLabs to Plivo)

<Steps>
  <Step title="Access Plivo Console">
    Sign in to the Plivo Console.
  </Step>

  <Step title="Navigate to Zentrunk Dashboard">
    Go to the Zentrunk Dashboard in your Plivo account.
  </Step>

  <Step title="Create outbound SIP trunk">
    1. Select "Create New Outbound Trunk" and provide a descriptive name for your trunk.
    2. Under Trunk Authentication, click "Add New Credentials List".
    3. Add a username and password that you'll use to authenticate outbound calls.
    4. Select "Create Credentials List". 5. Save your credentials list and select "Create Trunk" to complete your outbound trunk configuration.
  </Step>

  <Step title="Note your termination URI">
    After creating the outbound trunk, note the termination URI (typically in the format
    `sip:yourusername@yourplivotrunk.sip.plivo.com`). You'll need this information when configuring
    the SIP trunk in ElevenLabs.
  </Step>
</Steps>

<Warning>
  Once you've set up your Plivo SIP trunk, follow the [SIP trunking
  guide](/docs/agents-platform/phone-numbers/sip-trunking) to finish the setup ElevenLabs as well.
</Warning>


# Genesys

> Integrate ElevenLabs Agents with Genesys using native Audio Connector integration.

## Overview

This guide explains how to integrate ElevenLabs Agents with Genesys Cloud using the Audio Connector integration. This integration enables seamless voice AI capabilities within your existing Genesys contact center infrastructure over websocket, without requiring SIP trunking.

## How Genesys integration works

The Genesys integration uses a native WebSocket connection through the Audio Connector integration:

1. **WebSocket connection**: Direct connection to ElevenLabs using the Audio Connector integration in Genesys Cloud
2. **Real-time audio**: Bidirectional audio streaming between Genesys and ElevenLabs agents
3. **Flow integration**: Seamless integration within your Genesys Architect flows using bot actions
4. **Dynamic variables**: Support for passing context and data between Genesys and ElevenLabs

## Requirements

Before setting up the Genesys integration, ensure you have:

1. Genesys Cloud CX license with bot flow capabilities
2. Administrator access to Genesys Cloud organization
3. A configured ElevenLabs account and ElevenLabs agent
4. ElevenLabs API key

## Setting up the Audio Connector integration

<Steps>
  <Step title="Access Genesys Cloud Admin">
    Sign in to your Genesys Cloud organization with administrator privileges.
  </Step>

  <Step title="Navigate to Integrations">
    Go to Admin → Integrations in the Genesys Cloud interface.
  </Step>

  <Step title="Create Audio Connector integration">
    1. Click "Add Integration" and search for "Audio Connector", and click "Install"

    2. Select the Audio Connector integration type

    3. Provide a descriptive name for your integration
  </Step>

  <Step title="Configure authentication">
    1. Navigate to the Configuration section of your Audio Connector integration

    2. In Properties, in the Base Connection URI field, enter the appropriate URL for your environment:

       | Environment                | Base Connection URI                                                   |
       | -------------------------- | --------------------------------------------------------------------- |
       | Default (US/International) | `wss://api.elevenlabs.io/v1/convai/conversation/genesys`              |
       | EU Residency               | `wss://api.eu.residency.elevenlabs.io/v1/convai/conversation/genesys` |
       | India Residency            | `wss://api.in.residency.elevenlabs.io/v1/convai/conversation/genesys` |

       <Info>
         If your ElevenLabs account is on an isolated residency environment (EU or India), you must use
         the corresponding residency URL. Using the wrong URL will result in authentication failures.
         Learn more about [data residency](/docs/overview/administration/data-residency).
       </Info>

    3. In Credentials, enter your ElevenLabs API key in the authentication configuration

    4. Save the integration configuration
  </Step>

  <Step title="Activate the integration">
    Set the integration status to "Active" to enable the connection.
  </Step>
</Steps>

## Configuring your Genesys flow

<Steps>
  <Step title="Open Architect">
    Navigate to Admin → Architect in Genesys Cloud.
  </Step>

  <Step title="Create or edit a flow">
    Open an existing inbound, outbound, or in-queue call flow, or create a new one where you want to
    use the ElevenLabs agent.
  </Step>

  <Step title="Add bot action">
    1. In your flow, add a "Call Audio Connector" action from the Bot category

    2. Select your Audio Connector integration from the integration dropdown

    3. In the Connector ID field, specify your ElevenLabs agent ID
  </Step>

  <Step title="Configure session variables (optional)">
    If you need to pass context to your ElevenLabs agent, configure input session variables in the bot
    action. These will be available as dynamic variables in your ElevenLabs agent.
  </Step>

  <Step title="Publish your flow">
    Save and publish your flow to make the integration active.
  </Step>
</Steps>

## Agent configuration requirements

Your ElevenLabs Agents agent must be configured with specific audio settings for Genesys compatibility:

### Audio format requirements

* **TTS output format**: Set to μ-law 8000 Hz in Agent Settings → Voice
* **User input audio format**: Set to μ-law 8000 Hz in Agent Settings → Advanced

### Supported client events

The Genesys integration supports only the following client events:

* **Audio events**: For processing voice input from callers
* **Interruption events**: For handling caller interruptions during agent speech

<Note>
  Other client event types are not supported in the Genesys integration and will be silently ignored
  if configured.
</Note>

## Session variables

You can pass dynamic context from your Genesys flow to your ElevenLabs agent using input session variables and receive data back through output session variables. Session variables can also be used to override specific agent configuration settings directly from your Genesys flow.

### Input session variables

1. **In Genesys flow**: Define input session variables in your "Call Audio Connector" action
2. **In ElevenLabs agent**: Variables are available as dynamic variables and/or override configuration settings
3. **Usage**: Reference these variables in your agent's conversation flow or system prompts

Learn more about [dynamic variables](/docs/agents-platform/customization/personalization/dynamic-variables).

#### Configuration overrides

The following session variables can modify your agent's configuration at runtime:

* **`system__override_system_prompt`**: Overrides the agent's system prompt.
* **`system__override_first_message`**: Overrides the agent's first message to the user.
* **`system__override_language`**: Sets the agent's language for this session.
* **`system__override_voice_id`**: Sets the agent's voice ID for this session.

### Example usage

Genesys flow input session variables:

* `customer_name = "John Smith"`
* `system__override_first_message = "Hello! Welcome to our support line."`
* `system__override_language = "en"`

ElevenLabs agent prompt: Hi \{\{customer\_name}}, how can I help you today?

### Output session variables

You can now receive data from your ElevenLabs agent back to your Genesys flow using output session variables.

Any data collected through [Data Collection](/docs/agents-platform/customization/agent-analysis/data-collection) in your ElevenLabs agent will be available as output session variables in your Genesys flow after the conversation ends.

### Example usage

After your ElevenLabs agent conversation completes, you can use the output variables in your Genesys flow:

1. **Decision logic**: Use output variables in decision nodes to route calls
2. **Data processing**: Pass conversation data to external systems
3. **Reporting**: Include conversation outcomes in your contact center analytics

## Transfer to number functionality

The ElevenLabs integration now supports call transfers back to Genesys for routing to specific numbers or queues.

### Setting up transfers

<Steps>
  <Step title="Configure a data collection item">
    In your ElevenLabs agent, add a data collection item with a detailed identifier and description to collect where the user should be transferred.
  </Step>

  <Step title="Update agent prompt">
    Add instructions to your agent's system prompt to use the end\_call tool when a transfer is requested. For example:

    ```
    If the caller requests to be transferred to a specific department or asks to
    speak with a human agent, use the end_call tool to end the conversation.
    ```
  </Step>

  <Step title="Configure Genesys flow logic">
    In your Genesys Architect flow, add decision nodes after the Audio Connector action to check output variables and route the call accordingly:

    1. Use output session variables to determine if a transfer was requested
    2. Configure routing logic based on the transfer type or destination
    3. Use Genesys native transfer capabilities to complete the transfer
  </Step>
</Steps>

### Example transfer flow

1. **Customer request**: "I need to speak with billing"
2. **Agent response**: "I'll transfer you to our billing department"
3. **Agent action**: Uses end\_call tool
4. **Data collection**: Data collection field is populated
5. **Genesys flow**: Checks output variable and routes to billing queue

## Limitations and unsupported features

The following tools and features are not supported in the Genesys integration:

### Unsupported tools

* **Client tool**: Not compatible with Genesys WebSocket integration

## Troubleshooting

<AccordionGroup>
  <Accordion title="WebSocket connection fails">
    Verify that your API key is correctly configured in the Audio Connector integration and the ElevenLabs agent ID is correctly configured in the Connector ID field in your Architect flow.
    If there are any dynamic variables defined on your agent, they must be passed in as input session variables.
  </Accordion>

  <Accordion title="Session variables not working">
    Verify that input session variables are properly defined in your Genesys flow's "Call Audio Connector" action and that they're referenced correctly in your ElevenLabs agent using the \{\{variable\_name}} syntax.
  </Accordion>
</AccordionGroup>


# WhatsApp

> Connect your WhatsApp business account with ElevenLabs Agents

## Overview

You can connect your WhatsApp business account to an ElevenLabs Agent. The agent can then handle:

* Text conversations
* Inbound calls
* Outbound calls (one-off and batch)

## Importing a WhatsApp business account

<Steps>
  <Step title="Import your account">
    Go to the [WhatsApp page](https://elevenlabs.io/app/agents/whatsapp) and click the ***Import account*** button:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/734d6e0c2af1c50b769700e084368bed2a8c7eccf47aece6cfb6fc5ca7623f44/assets/images/agents/whatsapp/main-page.png" alt="WhatsApp page" />
    </Frame>
  </Step>

  <Step title="Authorize ElevenLabs">
    This will open the authorization flow where you select your account and give ElevenLabs permission to manage it:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9e5238e98f926582db314e9debc187a7dc29fd38a980cb732b4563b373110351/assets/images/agents/whatsapp/auth-flow.png" alt="WhatsApp authorization flow" />
    </Frame>
  </Step>

  <Step title="Assign an agent">
    When you finish importing your account, you will be taken to its settings page where you can assign an agent to it:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2c458308fed920cb4cbd9399f5d84575ccc642a8049c6d3aec5c74b92126cea2/assets/images/agents/whatsapp/account-page.png" alt="WhatsApp account page" />
    </Frame>

    <Info>
      If you don't assign an agent to your account, inbound messages will be ignored and inbound calls
      will be rejected. However, you will still be able to make outbound calls.
    </Info>
  </Step>

  <Step title="Configure WhatsApp Manager">
    Go to [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) to:

    * Configure your profile picture, etc.: open the ***Phone numbers*** page, select a phone number and go to the ***Profile*** tab
    * Allow voice calls: open the ***Phone numbers*** page, select a phone number and go to the ***Call settings*** tab
    * If you want to make outbound calls, add a payment method: open the ***Overview*** page and click the ***Add payment method*** button
  </Step>
</Steps>

## Text conversations

### Inbound

You can send a text message to your WhatsApp business account and the agent will respond:

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4c31b4d2b5eccccd7cddfa81144176a6d3c32f4670add5306f3a6ef78bc05244/assets/images/agents/whatsapp/text-conversation.png" alt="WhatsApp text conversation" width="300" />
</Frame>

The conversation will be ended either by the ***End conversation*** system tool (if you have it enabled on your agent) or after the ***Max conversation duration*** timeout.

<Info>
  There is currently no indication on the user side that the conversation ended, which can lead to a
  confusing user experience. We will soon add a setting that will let you specify a message the
  agent will send before ending the conversation due to timeout.
</Info>

### Outbound

You can start a conversation by sending an outbound message.

First, go to [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates) and create a message template. Then call [the API](/docs/api-reference/whats-app/outbound-message).

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/00da0b9efa23eb168ce9a1562ce3c90964a8ddb4b6affae81c773ab763dbd4f8/assets/images/agents/whatsapp/text-conversation-outbound.png" alt="WhatsApp text conversation" width="300" />
</Frame>

## Calls

### Inbound

You can call your WhatsApp business account and the agent will respond. During the call, you can also send text messages and they will be incorporated into the conversation.

### Outbound

Making an outbound call requires permission from the user. You can read more about this in [WhatsApp documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). When you schedule an outbound call, we will automatically send a template message with a call permission request if necessary, and make the call as soon as the user approves it.

First, go to [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates) and create a message template with a call permission request component.

You can then go to the [WhatsApp page](https://elevenlabs.io/app/agents/whatsapp), select your account, and click the ***Outbound call*** button. This will open a dialog where you select an agent, provide a WhatsApp user ID to call, and the call permission request template to use:

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4/assets/images/agents/whatsapp/outbound-call-dialog.png" alt="WhatsApp outbound call dialog" />
</Frame>

Alternatively, you can schedule the call via [the API](/docs/api-reference/whats-app/outbound-call) or schedule multiple calls with [batch calling](/docs/agents-platform/phone-numbers/batch-calls).

## Next steps: personalization

We set the `{{system__caller_id}}` and `{{system__called_number}}` [dynamic variables](/docs/agents-platform/customization/personalization/dynamic-variables) to the WhatsApp user ID and your WhatsApp phone number ID (or vice versa, depending on who started the conversation). You can use those in a tool or a [conversation initiation webhook](/docs/agents-platform/customization/personalization/twilio-personalization) to personalize conversations.

<Info>
  You can find your WhatsApp phone number ID by going to the [WhatsApp
  page](https://elevenlabs.io/app/agents/whatsapp), clicking the menu next to your account and
  selecting ***Copy phone number ID***.
</Info>

## FAQ

<AccordionGroup>
  <Accordion title="Pricing">
    Meta charges for outbound calls and call permission requests sent outside of a [Customer Service
    Window](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows).
    You will not be able to make outbound calls until you add a payment method to your WhatsApp
    business account. You can read more in [WhatsApp
    documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing).
  </Accordion>

  <Accordion title="Zero-Retention Mode">
    [Zero-Retention Mode](/docs/developers/resources/zero-retention-mode) limits our ability to
    provide certain functionality: we ignore messages and disallow outbound calls.
  </Accordion>
</AccordionGroup>


# WhatsApp tools

> Let your agent send messages on WhatsApp with tools

## Overview

You can give your agent a tool to send messages on WhatsApp, even during conversations on another channel (e.g. phone).

## Setup

<Steps>
  <Step title="Import your account">
    Follow the instructions [here](/docs/agents-platform/whatsapp) to import your WhatsApp business
    account.
  </Step>

  <Step title="Add an integration">
    Go to the [Integrations page](https://elevenlabs.io/app/agents/integrations), click the ***Add
    integration*** button, select WhatsApp and connect your account:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e560b1b2a4345bd2fbe9519f7146b87d195268955d2b2aa2c6221629d97e4384/assets/images/agents/whatsapp/integration.png" alt="WhatsApp integration" />
    </Frame>
  </Step>

  <Step title="Add a tool">
    Go to the [Tools page](https://elevenlabs.io/app/agents/tools), click the ***Add integration
    tool*** button, select the WhatsApp integration and the ***Send Message*** tool:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e85dcc3a3e3581250604311c516e080fb7f61f100b98b4b55be5f6071866e888/assets/images/agents/whatsapp/tool.png" alt="WhatsApp tool" />
    </Frame>
  </Step>
</Steps>

## Using the tool

<Steps>
  <Step title="Create a message template">
    Go to [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/), open the
    ***Manage templates*** page and create a message template:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e2d2c8bcab0b4c664261a57658627fd4368fc00e4768e4bd4c16264c59d07e16/assets/images/agents/whatsapp/template-simple.png" alt="WhatsApp message template" />
    </Frame>

    <Info>
      The tool currently only supports parameters in message body.
    </Info>
  </Step>

  <Step title="Configure your agent">
    Go to your agent configuration and add the tool:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0e078a4206030111493387ec6c9bc2235106ac3cb763d4555dd1ae7307c6d46a/assets/images/agents/whatsapp/tool-agent-config-tools.png" alt="Agent configuration: tools" />
    </Frame>

    In the system prompt, tell the agent: - when to use the tool - what template name and language
    code to use - what parameters to pass

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/893aa34f7bd3e01a0cbb919f08f801398de318d46e1d8d1a6c72a945193f7de9/assets/images/agents/whatsapp/tool-agent-config-prompt.png" alt="Agent configuration: prompt" />
    </Frame>
  </Step>

  <Step title="Test">
    Finally, it's time to test the tool configuration:

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/47d48232a04cd47112d5637288c6225761f7f66f3016f5fc7d9cf38a34b3782d/assets/images/agents/whatsapp/tool-conversation.png" alt="Test conversation" />
    </Frame>

    <Frame background="subtle">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b3809101caa5d38cf7ea761feb38f4ee316bfde4bef20e2e22eca6b14d0262f/assets/images/agents/whatsapp/tool-message-simple.png" alt="Test message received" width="300" />
    </Frame>
  </Step>
</Steps>


# Batch calling

> Initiate multiple outbound calls simultaneously with your ElevenLabs agents.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/TIOnL1TwzBs" title="Batch Calling Tutorial" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

<Note>
  When conducting outbound call campaigns, ensure compliance with all relevant regulations,
  including the [TCPA (Telephone Consumer Protection Act)](/docs/agents-platform/legal/tcpa) and any
  applicable state laws.
</Note>

## Overview

Batch Calling enables you to initiate multiple outbound calls simultaneously using your configured ElevenLabs agents. This feature is ideal for scenarios such as sending notifications, conducting surveys, or delivering personalized messages to a large list of recipients efficiently.
This feature is available for both phone numbers added via the [native Twilio integration](/docs/agents-platform/phone-numbers/twilio-integration/native-integration) and [SIP trunking](/docs/agents-platform/phone-numbers/sip-trunking).

### Key features

* **Upload recipient lists**: Easily upload recipient lists in CSV or XLS format.
* **Dynamic variables**: Personalize calls by including dynamic variables (e.g., `user_name`) in your recipient list as separate columns.
* **Agent selection**: Choose the specific ElevenLabs agent to handle the calls.
* **Scheduling**: Send batches immediately or schedule them for a later time.
* **Real-time monitoring**: Track the progress of your batch calls, including overall status and individual call status.
* **Detailed reporting**: View comprehensive details of completed batch calls, including individual call recipient information.

## Concurrency

When batch calls are initiated, they automatically utilize the minimum of either 50% of your workspace's concurrency limit or 70% of your agent's concurrency limit.
This ensures that sufficient concurrent capacity remains available for other conversations, including incoming calls and calls via the widget.

## Requirements

* An ElevenLabs account with an [agent setup](https://elevenlabs.io/app/agents).
* A phone number imported

<Warning>
  Zero Retention Mode (ZRM) cannot be enabled for batch calls. If your use case requires ZRM, you
  will need to initiate calls individually rather than using the batch calling feature.
</Warning>

## Creating a batch call

Follow these steps to create a new batch call:

<Steps>
  <Step title="Navigate to Batch Calling">
    Access the [Outbound calls interface](https://elevenlabs.io/app/agents/batch-calling) from the
    ElevenAgents dashboard
  </Step>

  <Step title="Initiate a new batch call">
    Click on the "Create a batch call" button. This will open the "Create a batch call" page.

    <Frame background="subtle" caption="The 'Create a batch call' interface.">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/defec00e1f267346775021283bdc6038cfabcd27427dffb7cd7e5cd9382b53e0/assets/images/conversational-ai/batch-call-creation.png" alt="Create a batch call page showing fields for batch name, phone number, agent selection, recipient upload, and timing options." />
    </Frame>
  </Step>

  <Step title="Configure batch details">
    * **Batch name**: Enter a descriptive name for your batch call (e.g., "Delivery notice", "Weekly Update Notifications").
    * **Phone number**: Select the phone number that will be used to make the outbound calls.
    * **Select agent**: Choose the pre-configured ElevenLabs agent that will handle the conversations for this batch.
  </Step>

  <Step title="Upload recipients">
    * **Upload File**: Upload your recipient list. Supported file formats are CSV and XLS.
    * **Formatting**:
      * The `phone_number` column is mandatory in your uploaded file (if your agent has a `phone_number` dynamic variable that also has to be set, please rename it).
      * You can include other columns (e.g., `name`, `user_name`) which will be passed as dynamic variables to personalize the calls.
      * A template is available for download to ensure correct formatting.

    <Note title="Setting overrides">
      The following column headers are special fields that are used to override an agent's initial
      configuration:

      * language
      * first\_message
      * system\_prompt
      * voice\_id

      The batch call will fail if those fields are passed but are not set to be overridable in the agent's security settings. See more
      [here](/docs/agents-platform/customization/personalization/overrides).
    </Note>
  </Step>

  <Step title="Set timing">
    * **Send immediately**: The batch call will start processing as soon as you submit it. -
      **Schedule for later**: Choose a specific date, time, and timezone for the batch call to begin.
  </Step>

  <Step title="Submit the batch call">
    * You may "Test call" with a single recipient before submitting the entire batch. - Click "Submit
      a Batch Call" to finalize and initiate or schedule the batch.
  </Step>
</Steps>

## Managing and monitoring batch calls

Once a batch call is created, you can monitor its progress and view its details.

### Batch calling overview

The Batch Calling overview page displays a list of all your batch calls.

<Frame background="subtle" caption="Overview of batch calls, displaying status, progress, and other details for each batch.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a371de67085f7c63765a90dacbe2ba50b6d5cb8544cb8554233d9a39567b0994/assets/images/conversational-ai/batch-call-summary.png" alt="Batch Calling overview page listing several batch calls with their status, recipient count, and progress." />
</Frame>

### Viewing batch call details

Clicking on a specific batch call from the overview page will take you to its detailed view, from where you can view individual conversations.

<Frame background="subtle" caption="Detailed view of a specific batch call, showing summary statistics and a list of call recipients with their individual statuses.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a9ef3ded53870849fea0c86bc9ddf9ae43ca86ba98199b988370a67d11a447ee/assets/images/conversational-ai/batch-call-completed-summary.png" alt="Batch call details page showing a summary (status, total recipients, started, progress) and a list of call recipients with phone number, dynamic variables, and status." />
</Frame>

## API Usage

You can also manage and initiate batch calls programmatically using the ElevenLabs API. This allows for integration into your existing workflows and applications.

* [List batch calls](/docs/api-reference/batch-calling/list) - Retrieve all batch calls in your workspace
* [Create batch call](/docs/api-reference/batch-calling/create) - Submit a new batch call with agent, phone number, and recipient list


# Operate

> Monitor, test, and optimize your agents at scale.

This section provides tools and best practices for running production agents, from testing and quality assurance to analytics and cost optimization.

### Monitor and optimize

| Goal                         | Guide                                                                         | Description                                          |
| ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- |
| Test agent behavior          | [Testing](/docs/agents-platform/customization/agent-testing)                  | Create and run automated tests for your agents       |
| Analyze conversation quality | [Conversation analysis](/docs/agents-platform/customization/agent-analysis)   | Extract insights and evaluate conversation outcomes  |
| Track metrics & analytics    | [Analytics](/docs/agents-platform/dashboard)                                  | Monitor performance metrics and conversation history |
| Configure data retention     | [Privacy](/docs/agents-platform/customization/privacy)                        | Set retention policies for conversations and audio   |
| Reduce LLM costs             | [Cost optimization](/docs/agents-platform/customization/llm/optimizing-costs) | Monitor and optimize language model expenses         |

## Next steps

<CardGroup cols={2}>
  <Card title="Testing" href="/docs/agents-platform/customization/agent-testing">
    Set up automated tests
  </Card>

  <Card title="Analytics" href="/docs/agents-platform/dashboard">
    View performance metrics
  </Card>

  <Card title="Cost Optimization" href="/docs/agents-platform/customization/llm/optimizing-costs">
    Reduce LLM costs
  </Card>

  <Card title="Conversation Analysis" href="/docs/agents-platform/customization/agent-analysis">
    Analyze conversations
  </Card>
</CardGroup>


# Agent Testing

> Build confidence in your agent's behavior with automated testing

The agent testing framework enables you to move from slow, manual phone calls to a fast, automated, and repeatable testing process. Create comprehensive test suites that verify both conversational responses and tool usage, ensuring your agents behave exactly as intended before deploying to production.

## Video Walkthrough

<Frame background="subtle">
  <iframe width="100%" height="400" src="https://www.youtube.com/embed/SvyrPTNpWas" title="Agent Testing Walkthrough" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />
</Frame>

## Overview

The framework consists of two complementary testing approaches:

* **Scenario Testing (LLM Evaluation)** - Validates conversational abilities and response quality
* **Tool Call Testing** - Ensures proper tool usage and parameter validation

Both test types can be created from scratch or directly from existing conversations, allowing you to quickly turn real-world interactions into repeatable test cases.

## Scenario Testing (LLM Evaluation)

Scenario testing evaluates your agent's conversational abilities by simulating interactions and assessing responses against defined success criteria.

### Creating a Scenario Test

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/62de63965584fd1b2368edfb204bd90495d03ba87fe137889a5f396859dc4dbc/assets/images/conversational-ai/agent-llm-eval-test.png" alt="Scenario Testing Interface" />
</Frame>

<Steps>
  <Step title="Define the scenario">
    Create context for the text. This can be multiple turns of interaction that sets up the specific scenario you want to evaluate. Our testing framework currently only supports evaluating a single next step in the conversation. For simulating entire conversations, see our [simulate conversation endpoint](/docs/api-reference/agents/simulate-conversation) and [conversation simulation guide](/docs/agents-platform/guides/simulate-conversations).

    **Example scenario:**

    ```
    User: "I'd like to cancel my subscription. I've been charged twice this month and I'm frustrated."
    ```
  </Step>

  <Step title="Set success criteria">
    Describe in plain language what the agent's response should achieve. Be specific about the
    expected behavior, tone, and actions.

    **Example criteria:**

    * The agent should acknowledge the customer's frustration with empathy
    * The agent should offer to investigate the duplicate charge
    * The agent should provide clear next steps for cancellation or resolution
    * The agent should maintain a professional and helpful tone
  </Step>

  <Step title="Provide examples">
    Supply both success and failure examples to help the evaluator understand the nuances of your
    criteria.

    **Success Example:**

    > "I understand how frustrating duplicate charges can be. Let me look into this right away for you. I can see there were indeed two charges this month - I'll process a refund for the duplicate charge immediately. Would you still like to proceed with cancellation, or would you prefer to continue once this is resolved?"

    **Failure Example:**

    > "You need to contact billing department for refund issues. Your subscription will be cancelled."
  </Step>

  <Step title="Run the test">
    Execute the test to simulate the conversation with your agent. An LLM evaluator compares the
    actual response against your success criteria and examples to determine pass/fail status.
  </Step>
</Steps>

### Creating Tests from Conversations

Transform real conversations into test cases with a single click. This powerful feature creates a feedback loop for continuous improvement based on actual performance.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7b0762965b7edb46ed6b693c126c00e9aa3e7c98dae7aa89a981b5465b949750/assets/images/conversational-ai/agent-test-from-conv.gif" alt="Creating test from conversation" />
</Frame>

When reviewing call history, if you identify a conversation where the agent didn't perform well:

1. Click "Create test from this conversation"
2. The framework automatically populates the scenario with the actual conversation context
3. Define what the correct behavior should have been
4. Add the test to your suite to prevent similar issues in the future

## Tool Call Testing

Tool call testing verifies that your agent correctly uses tools and passes the right parameters in specific situations. This is critical for actions like call transfers, data lookups, or external integrations.

### Creating a Tool Call Test

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/291c48ac70376efa1991014f7b3ff90eb9910c9adffe250f2bf521c707c5c755/assets/images/conversational-ai/agent-tool-call-test.png" alt="Tool Call Testing Interface" />
</Frame>

<Steps>
  <Step title="Select the tool">
    Choose which tool you expect the agent to call in the given scenario (e.g.,
    `transfer_to_number`, `end_call`, `lookup_order`).
  </Step>

  <Step title="Define expected parameters">
    Specify what data the agent should pass to the tool. You have three validation methods:

    <Accordion title="Validation Methods">
      **Exact Match**\
      The parameter must exactly match your specified value.

      ```
      Transfer number: +447771117777
      ```

      **Regex Pattern**
      The parameter must match a specific pattern.

      ```
      Order ID: ^ORD-[0-9]{8}$
      ```

      **LLM Evaluation**
      An LLM evaluates if the parameter is semantically correct based on context.

      ```
      Message: "Should be a polite message mentioning the connection"
      ```
    </Accordion>
  </Step>

  <Step title="Configure dynamic variables">
    When testing in development, use dynamic variable values that match those that would be actual
    values in production. Example: `{{ customer_name }}` or `{{ order_id }}`
  </Step>

  <Step title="Run and validate">
    Execute the test to ensure the agent calls the correct tool with proper parameters.
  </Step>
</Steps>

### Critical Use Cases

Tool call testing is essential for high-stakes scenarios:

* **Emergency Transfers**: Ensure medical emergencies always route to the correct number
* **Data Security**: Verify sensitive information is never passed to unauthorized tools
* **Business Logic**: Confirm order lookups use valid formats and authentication

## Development Workflow

The framework supports an iterative development cycle that accelerates agent refinement:

<Steps>
  <Step title="Write tests first">
    Define the desired behavior by creating tests for new features or identified issues.
  </Step>

  <Step title="Test and iterate">
    Run tests instantly without saving changes. Watch them fail, then adjust your agent's prompts or
    configuration.
  </Step>

  <Step title="Refine until passing">
    Continue tweaking and re-running tests until all pass. The framework provides immediate feedback
    without requiring deployment.
  </Step>

  <Step title="Save with confidence">
    Once tests pass, save your changes knowing the agent behaves as intended.
  </Step>
</Steps>

## Running Tests

Navigate to the Tests tab in your agent's interface. From there, you can run individual tests or execute your entire test suite at once using the "Run All Tests" button.

<Frame background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b1becf589a1373a780dad1109fd25e0e910d7aa821b09b047133553b1895914b/assets/images/conversational-ai/testrun.gif" alt="Running tests on an agent" />
</Frame>

## Batch Testing and CI/CD Integration

### Running Test Suites

Execute all tests at once to ensure comprehensive coverage:

1. Select multiple tests from your test library
2. Run as a batch to identify any regressions
3. Review consolidated results showing pass/fail status for each test

### CLI Integration

Integrate testing into your development pipeline using the ElevenLabs CLI:

```bash
# Run all tests for an agent
elevenlabs agents test <your_agent_id>
```

This enables:

* Automated testing on every code change
* Prevention of regressions before deployment
* Consistent agent behavior across environments

## Best Practices

<Cards>
  <Card title="Evaluate agent persona consistency" icon="duotone shield-check">
    Test that your agent maintains its defined personality, tone, and behavioral boundaries across
    diverse conversation scenarios and emotional contexts.
  </Card>

  <Card title="Verify complex multi-turn reasoning" icon="duotone phone-volume">
    Create scenarios that test the agent's ability to maintain context, follow conditional logic,
    and handle state transitions across extended conversations.
  </Card>

  <Card title="Test against prompt injection attempts" icon="duotone list-check">
    Evaluate how your agent responds to attempts to override its instructions or extract sensitive
    system information through adversarial inputs.
  </Card>

  <Card title="Assess ambiguous intent resolution" icon="duotone flask">
    Test how effectively your agent clarifies vague requests, handles conflicting information, and
    navigates situations where user intent is unclear.
  </Card>
</Cards>

## Next Steps

* [View CLI Documentation](/docs/agents-platform/operate/cli) for automated testing setup
* [Explore Tool Configuration](/docs/agents-platform/customization/tools) to understand available tools
* [Read the Prompting Guide](/docs/agents-platform/best-practices/prompting-guide) for writing testable prompts


# Agent versioning

> Safely experiment with agent configurations using branches, versions, and traffic deployment

Agent versioning allows you to experiment with different configurations of your agent without risking your production setup. Create isolated branches, test changes, and gradually roll out updates using traffic percentage deployment.

## Overview

The versioning system provides:

* **Immutable snapshots** of your agent configuration at any point in time
* **Isolated branches** for testing changes before going live
* **Traffic splitting** to gradually roll out changes to a percentage of users
* **Merging** to bring successful experiments back to main

<Note>
  Once versioning is enabled on an agent, it cannot be disabled. Consider this before enabling
  versioning on existing agents.
</Note>

## Core concepts

### Versions

A version is an immutable snapshot of an agent's configuration at a specific point in time. Each version has a unique ID (format: `agtvrsn_xxxx`) and contains:

* `conversation_config` - System prompt, LLM settings, voice configuration, tools, knowledge base
* `platform_settings` - Versioned subset including evaluation, widget, data collection, and safety settings
* `workflow` - Complete workflow definition with nodes and edges

Versions are created automatically when you save changes to a versioned agent. Once created, a version cannot be modified.

### Branches

Branches are named lines of development, similar to git branches. They allow you to work on changes in isolation before merging back to the main branch.

* Every versioned agent has a **Main** branch that cannot be deleted or archived
* Additional branches can be created from any version on the main branch
* Each branch has: id (`agtbrch_xxxx`), name, description, and a list of versions
* Branch names can contain: letters, numbers, and `() [] {} - / .` (max 140 characters)

### Traffic deployment

Traffic can be split across multiple branches by percentage, enabling gradual rollouts and A/B testing.

* Percentages must always total exactly **100%**
* Traffic routing is **deterministic** based on conversation ID (the same user consistently routes to the same branch)
* Only non-archived branches with 0% traffic can be archived

### Drafts

Unsaved changes are stored as drafts, allowing you to work on changes without immediately creating a new version.

* Drafts are **per-user, per-branch** (each team member has their own draft)
* Drafts are automatically discarded when a new version is committed
* Drafts are also discarded when merging into a branch

## Enabling versioning

Versioning is opt-in and must be explicitly enabled. You can enable it when creating a new agent or on an existing agent.

<Warning>
  Once enabled, versioning cannot be disabled. This is a permanent change to your agent.
</Warning>

### Enable when creating an agent

<CodeBlocks>
  ```python
  from elevenlabs.client import ElevenLabs
  from elevenlabs.types import *

  client = ElevenLabs(api_key="your-api-key")

  agent = client.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
  agent=AgentConfig(
  first_message="Hello! How can I help you today?",
  prompt=AgentPromptConfig(
  prompt="You are a helpful assistant."
  )
  )
  ),
  enable_versioning=True
  )

  print(f"Agent created with versioning: {agent.agent_id}")

  ```

  ```javascript
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

  const client = new ElevenLabsClient({ apiKey: 'your-api-key' });

  const agent = await client.conversationalAi.agents.create({
    conversationConfig: {
      agent: {
        firstMessage: 'Hello! How can I help you today?',
        prompt: {
          prompt: 'You are a helpful assistant.',
        },
      },
    },
    enableVersioning: true,
  });

  console.log(`Agent created with versioning: ${agent.agentId}`);

  ```
</CodeBlocks>

### Enable on an existing agent

<CodeBlocks>
  ```python
  agent = client.conversational_ai.agents.update(
      agent_id="your-agent-id",
      enable_versioning_if_not_enabled=True
  )
  ```

  ```javascript
  const agent = await client.conversationalAi.agents.update('your-agent-id', {
    enableVersioningIfNotEnabled: true,
  });
  ```
</CodeBlocks>

Enabling versioning creates the initial "Main" branch with the first version containing the current agent configuration.

## Working with branches

### Creating a branch

Branches can only be created from versions on the main branch. You can optionally include configuration changes that will be applied to the new branch's initial version.

<CodeBlocks>
  ```python
  branch = client.conversational_ai.agents.branches.create(
      agent_id="your-agent-id",
      parent_version_id="agtvrsn_xxxx",
      name="experiment-v2",
      description="Testing new prompt and voice settings"
  )

  print(f"Created branch: {branch.created_branch_id}")
  print(f"Initial version: {branch.created_version_id}")
  ```

  ```javascript
  const branch = await client.conversationalAi.agents.branches.create('your-agent-id', {
    parentVersionId: 'agtvrsn_xxxx',
    name: 'experiment-v2',
    description: 'Testing new prompt and voice settings',
  });

  console.log(`Created branch: ${branch.createdBranchId}`);
  console.log(`Initial version: ${branch.createdVersionId}`);

  ```
</CodeBlocks>

### Listing branches

<CodeBlocks>
  ```python
  branches = client.conversational_ai.agents.branches.list(
      agent_id="your-agent-id"
  )

  for branch in branches.branches:
  print(f"{branch.name}: {branch.id}")

  ```

  ```javascript
  const branches = await client.conversationalAi.agents.branches.list('your-agent-id');

  for (const branch of branches.branches) {
    console.log(`${branch.name}: ${branch.id}`);
  }

  ```
</CodeBlocks>

### Getting branch details

<CodeBlocks>
  ```python
  branch = client.conversational_ai.agents.branches.get(
      agent_id="your-agent-id",
      branch_id="agtbrch_xxxx"
  )

  print(f"Branch: {branch.name}")
  print(f"Versions: {len(branch.versions)}")

  ```

  ```javascript
  const branch = await client.conversationalAi.agents.branches.get('your-agent-id', 'agtbrch_xxxx');

  console.log(`Branch: ${branch.name}`);
  console.log(`Versions: ${branch.versions.length}`);

  ```
</CodeBlocks>

## Committing changes

When you update an agent with versioning enabled, specify the `branch_id` to create a new version on that branch.

<CodeBlocks>
  ```python
  agent = client.conversational_ai.agents.update(
      agent_id="your-agent-id",
      branch_id="agtbrch_xxxx",
      conversation_config=ConversationalConfig(
          agent=AgentConfig(
              prompt=AgentPromptConfig(
                  prompt="You are a friendly customer support agent."
              )
          )
      )
  )
  ```

  ```javascript
  const agent = await client.conversationalAi.agents.update(
    'your-agent-id',
    {
      conversationConfig: {
        agent: {
          prompt: {
            prompt: 'You are a friendly customer support agent.',
          },
        },
      },
    },
    { branchId: 'agtbrch_xxxx' }
  );
  ```
</CodeBlocks>

A new version is automatically created on the specified branch, and any existing draft for that user on that branch is discarded.

## Deploying traffic

Use the deployments endpoint to distribute traffic across branches. This enables gradual rollouts and A/B testing.

<CodeBlocks>
  ```python
  deployment = client.conversational_ai.agents.deployments.create(
      agent_id="your-agent-id",
      deployments=[
          {"branch_id": "agtbrch_main", "percentage": 90},
          {"branch_id": "agtbrch_xxxx", "percentage": 10}
      ]
  )
  ```

  ```javascript
  const deployment = await client.conversationalAi.agents.deployments.create('your-agent-id', {
    deployments: [
      { branchId: 'agtbrch_main', percentage: 90 },
      { branchId: 'agtbrch_xxxx', percentage: 10 },
    ],
  });
  ```
</CodeBlocks>

<Warning>
  All percentages must sum to exactly 100%. The deployment will fail if they don't.
</Warning>

Traffic routing is deterministic based on the conversation ID, ensuring the same user consistently reaches the same branch across sessions.

## Merging branches

When you're satisfied with changes on a branch, merge them back to the main branch.

<CodeBlocks>
  ```python
  merge = client.conversational_ai.agents.branches.merge(
      agent_id="your-agent-id",
      source_branch_id="agtbrch_xxxx",
      target_branch_id="agtbrch_main",
      archive_source_branch=True  # Default: true
  )
  ```

  ```javascript
  const merge = await client.conversationalAi.agents.branches.merge('your-agent-id', 'agtbrch_xxxx', {
    targetBranchId: 'agtbrch_main',
    archiveSourceBranch: true, // Default: true
  });
  ```
</CodeBlocks>

Merging:

* Creates a new version on the main branch with the source branch's configuration
* Optionally archives the source branch (default behavior)
* Automatically transfers traffic from the source branch to main

<Note>
  You can only merge into the main branch. Merging between non-main branches is not supported.
</Note>

## Archiving branches

Archive branches you no longer need. This helps keep your branch list organized.

<CodeBlocks>
  ```python
  client.conversational_ai.agents.branches.update(
      agent_id="your-agent-id",
      branch_id="agtbrch_xxxx",
      archived=True
  )
  ```

  ```javascript
  await client.conversationalAi.agents.branches.update('your-agent-id', 'agtbrch_xxxx', {
    archived: true,
  });
  ```
</CodeBlocks>

<Warning>
  You cannot archive a branch that has traffic allocated to it. Remove all traffic before archiving.
</Warning>

Archived branches can be unarchived by setting `archived=False`.

## Retrieving specific versions

You can retrieve an agent at a specific version or branch tip.

### Get agent at specific version

<CodeBlocks>
  ```python
  agent = client.conversational_ai.agents.get(
      agent_id="your-agent-id",
      version_id="agtvrsn_xxxx"
  )
  ```

  ```javascript
  const agent = await client.conversationalAi.agents.get('your-agent-id', {
    versionId: 'agtvrsn_xxxx',
  });
  ```
</CodeBlocks>

### Get agent at branch tip

<CodeBlocks>
  ```python
  agent = client.conversational_ai.agents.get(
      agent_id="your-agent-id",
      branch_id="agtbrch_xxxx"
  )
  ```

  ```javascript
  const agent = await client.conversationalAi.agents.get('your-agent-id', {
    branchId: 'agtbrch_xxxx',
  });
  ```
</CodeBlocks>

### Include draft changes

<CodeBlocks>
  ```python
  agent = client.conversational_ai.agents.get(
      agent_id="your-agent-id",
      branch_id="agtbrch_xxxx",
      include_draft=True
  )
  ```

  ```javascript
  const agent = await client.conversationalAi.agents.get('your-agent-id', {
    branchId: 'agtbrch_xxxx',
    includeDraft: true,
  });
  ```
</CodeBlocks>

## Settings reference

### Versioned settings

These settings can differ between versions and branches:

| Category                        | Settings                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversation config**         | System prompt, agent personality, LLM selection and parameters, voice settings (TTS model, voice ID), tools configuration, knowledge base, first message, language settings, turn detection, interruption settings                                                                                            |
| **Versioned platform settings** | `evaluation` - evaluation criteria, `widget` - widget appearance and behavior, `data_collection` - structured data extraction, `overrides` - conversation initiation overrides, `workspace_overrides` - webhooks configuration, `testing` - test configurations, `safety` - guardrails (IVC/non-IVC settings) |
| **Workflow**                    | Complete workflow definition (nodes and edges)                                                                                                                                                                                                                                                                |

### Per-agent settings

These settings are shared across all versions:

| Setting        | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `name`, `tags` | Agent name and tags (only updated when committing to main branch) |
| `auth`         | Authentication settings and allowlist                             |
| `call_limits`  | Concurrency and daily limits                                      |
| `privacy`      | Retention settings and zero-retention mode                        |
| `ban`          | Ban status (admin only)                                           |

<Note>
  Changes to name and tags on non-main branches don't persist to the agent until merged to main.
</Note>

## Best practices

<Steps>
  <Step title="Create tests before branching">
    Set up [automated tests](/docs/agents-platform/customization/agent-testing) that capture
    expected behavior before creating a new branch. This establishes a baseline and helps catch
    regressions early when iterating on your experiment.
  </Step>

  <Step title="Use descriptive branch names">
    Choose branch names that clearly communicate the purpose of the experiment. Include the feature
    name, hypothesis, or ticket number for easy reference (e.g., `feature/new-greeting-flow` or
    `experiment/shorter-responses`).
  </Step>

  <Step title="Document branch purposes">
    Use the branch description field to explain what hypothesis you're testing, what metrics define
    success, and any dependencies or considerations. This helps team members understand active
    experiments.
  </Step>

  <Step title="Use drafts for work-in-progress">
    Save drafts frequently while iterating on changes. This preserves your work without creating
    unnecessary versions. Only commit when you're ready to test or deploy.
  </Step>

  <Step title="Start with small traffic percentages">
    When deploying a new branch, begin with 5-10% of traffic. This limits exposure if issues arise
    while still providing meaningful data.
  </Step>

  <Step title="Monitor key metrics before increasing traffic">
    Use the [analytics dashboard](/docs/agents-platform/dashboard) to compare branch performance.
    Look for call completion rates, average conversation duration, success evaluation scores, and
    tool execution rates. Only increase traffic when metrics meet or exceed your main branch
    baseline.
  </Step>

  <Step title="Increase traffic gradually">
    Scale up traffic in increments (10% → 25% → 50% → 100%) as confidence grows. This approach
    minimizes risk while validating performance at each stage.
  </Step>

  <Step title="Keep branches short-lived">
    Merge successful experiments promptly to avoid configuration drift. Long-running branches become
    harder to merge and may conflict with other changes made to main.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Testing" href="/docs/agents-platform/customization/agent-testing">
    Set up automated tests for your agent versions
  </Card>

  <Card title="Analytics" href="/docs/agents-platform/dashboard">
    Monitor performance across different branches
  </Card>

  <Card title="Conversation Analysis" href="/docs/agents-platform/customization/agent-analysis">
    Analyze conversations to compare branch performance
  </Card>

  <Card title="CLI" href="/docs/agents-platform/operate/cli">
    Manage versioning from the command line
  </Card>
</CardGroup>


# Conversation analysis

> Analyze conversation quality and extract structured data from customer interactions.

Agent analysis provides powerful tools to systematically evaluate conversation performance and extract valuable information from customer interactions. These LLM-powered features help you measure agent effectiveness and gather actionable business insights.

<CardGroup cols={2}>
  <Card title="Success Evaluation" icon="chart-line" href="/docs/agents-platform/customization/agent-analysis/success-evaluation">
    Define custom criteria to assess conversation quality, goal achievement, and customer
    satisfaction.
  </Card>

  <Card title="Data Collection" icon="database" href="/docs/agents-platform/customization/agent-analysis/data-collection">
    Extract structured information from conversations such as contact details and business data.
  </Card>
</CardGroup>

## Overview

ElevenAgents provides two complementary analysis capabilities:

* **Success Evaluation**: Define custom metrics to assess conversation quality, goal achievement, and customer satisfaction
* **Data Collection**: Extract specific data points from conversations such as contact information, issue details, or any structured information

Both features process conversation transcripts using advanced language models to provide actionable insights that improve agent performance and business outcomes.

## Key Benefits

<AccordionGroup>
  <Accordion title="Performance Measurement">
    Track conversation success rates, customer satisfaction, and goal completion across all interactions to identify improvement opportunities.
  </Accordion>

  <Accordion title="Automated Data Extraction">
    Capture valuable business information without manual processing, reducing operational overhead and
    improving data accuracy.
  </Accordion>

  <Accordion title="Quality Assurance">
    Ensure agents follow required procedures and maintain consistent service quality through
    systematic evaluation.
  </Accordion>

  <Accordion title="Business Intelligence">
    Gather structured insights about customer preferences, behavior patterns, and interaction outcomes for strategic decision-making.
  </Accordion>
</AccordionGroup>

## Integration with Platform Features

Agent analysis integrates seamlessly with other ElevenAgents capabilities:

* **[Post-call Webhooks](/docs/agents-platform/workflows/post-call-webhooks)**: Receive evaluation results and extracted data via webhooks for integration with external systems
* **[Analytics Dashboard](/docs/agents-platform/dashboard)**: View aggregated performance metrics and trends across all conversations
* **[Agent Transfer](/docs/agents-platform/customization/tools/system-tools/agent-transfer)**: Use evaluation criteria to determine when conversations should be escalated

## Getting Started

<Steps>
  <Step title="Choose your analysis approach">
    Determine whether you need success evaluation, data collection, or both based on your business objectives.
  </Step>

  <Step title="Configure evaluation criteria">
    Set up [Success Evaluation](/docs/agents-platform/customization/agent-analysis/success-evaluation)
    to measure conversation quality and goal achievement.
  </Step>

  <Step title="Set up data extraction">
    Configure [Data Collection](/docs/agents-platform/customization/agent-analysis/data-collection) to
    capture structured information from conversations.
  </Step>

  <Step title="Monitor and optimize">
    Review results regularly and refine your criteria and extraction rules based on performance data.
  </Step>
</Steps>


# Success Evaluation

> Define custom criteria to assess conversation quality, goal achievement, and customer satisfaction.

Success evaluation allows you to define custom goals and success metrics for your conversations. Each criterion is evaluated against the conversation transcript and returns a result of `success`, `failure`, or `unknown`, along with a detailed rationale.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/hvuuRpvAlV0?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Success evaluation uses LLM-powered analysis to assess conversation quality against your specific business objectives. This enables systematic performance measurement and quality assurance across all customer interactions.

### How It Works

Each evaluation criterion analyzes the conversation transcript using a custom prompt and returns:

* **Result**: `success`, `failure`, or `unknown`
* **Rationale**: Detailed explanation of why the result was chosen

### Types of Evaluation Criteria

<Tabs>
  <Tab title="Goal Prompt Criteria">
    **Goal prompt criteria** pass the conversation transcript along with a custom prompt to an LLM to verify if a specific goal was met. This is the most flexible type of evaluation and can be used for complex business logic.

    **Examples:**

    * Customer satisfaction assessment
    * Issue resolution verification
    * Compliance checking
    * Custom business rule validation
  </Tab>
</Tabs>

## Configuration

<Steps>
  <Step title="Access agent settings">
    Navigate to your agent's dashboard and select the **Analysis** tab to configure evaluation criteria.

    <Frame background="subtle">
      ![Analysis settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fee8bc444d5436c71eae3829b9ec8d5cdb6a57c4d4efe6483d7bfed2b066e438/assets/images/conversational-ai/analysis-settings.png)
    </Frame>
  </Step>

  <Step title="Add evaluation criteria">
    Click **Add criteria** to create a new evaluation criterion.

    Define your criterion with:

    * **Identifier**: A unique name for the criterion (e.g., `user_was_not_upset`)
    * **Description**: Detailed prompt describing what should be evaluated

    <Frame background="subtle">
      ![Setting up evaluation criteria](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0e1ad5eec745d5733701dcf8cbf4f413473f55a0b5f26add4faac540dbbd086a/assets/images/conversational-ai/evaluation.gif)
    </Frame>

    <Note>
      Evaluation criteria are limited to 30 per agent.
    </Note>
  </Step>

  <Step title="View results">
    After conversations complete, evaluation results appear in your conversation history dashboard. Each conversation shows the evaluation outcome and rationale for every configured criterion.

    <Frame background="subtle">
      ![Evaluation results in conversation history](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/657888630b51010fa6920275cfbb8f3dce51c0cbcfdb8ecf3d5d938f17a8186a/assets/images/conversational-ai/evaluation_result.gif)
    </Frame>
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Writing effective evaluation prompts">
    * Be specific about what constitutes success vs. failure
    * Include edge cases and examples in your prompt
    * Use clear, measurable criteria when possible
    * Test your prompts with various conversation scenarios
  </Accordion>

  <Accordion title="Common evaluation criteria">
    * **Customer satisfaction**: "Mark as successful if the customer expresses satisfaction or their
      issue was resolved" - **Goal completion**: "Mark as successful if the customer completed the
      requested action (booking, purchase, etc.)" - **Compliance**: "Mark as successful if the agent
      followed all required compliance procedures" - **Issue resolution**: "Mark as successful if the
      customer's technical issue was resolved during the call"
  </Accordion>

  <Accordion title="Handling ambiguous results">
    The `unknown` result is returned when the LLM cannot determine success or failure from the transcript. This often happens with:

    * Incomplete conversations
    * Ambiguous customer responses
    * Missing information in the transcript

    Monitor `unknown` results to identify areas where your criteria prompts may need refinement.
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Customer Support Quality" icon="headset">
    Measure issue resolution rates, customer satisfaction, and support quality metrics to improve
    service delivery.
  </Card>

  <Card title="Sales Performance" icon="chart-up">
    Track goal achievement, objection handling, and conversion rates across sales conversations.
  </Card>

  <Card title="Compliance Monitoring" icon="shield-check">
    Ensure agents follow required procedures and capture necessary consent or disclosure
    confirmations.
  </Card>

  <Card title="Training & Development" icon="graduation-cap">
    Identify coaching opportunities and measure improvement in agent performance over time.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Evaluation criteria returning unexpected results">
    * Review your prompt for clarity and specificity
    * Test with sample conversations to validate logic
    * Consider edge cases in your evaluation criteria
    * Check if the transcript contains sufficient information for evaluation
  </Accordion>

  <Accordion title="High frequency of 'unknown' results">
    * Ensure your prompts are specific about what information to look for - Consider if conversations
      contain enough context for evaluation - Review transcript quality and completeness - Adjust
      criteria to handle common edge cases
  </Accordion>

  <Accordion title="Performance considerations">
    * Each evaluation criterion adds processing time to conversation analysis
    * Complex prompts may take longer to evaluate
    * Consider the trade-off between comprehensive analysis and response time
    * Monitor your usage to optimize for your specific needs
  </Accordion>
</AccordionGroup>

<Info>
  Success evaluation results are available through [Post-call
  Webhooks](/docs/agents-platform/workflows/post-call-webhooks) for integration with external
  systems and analytics platforms.
</Info>


# Data Collection

> Extract structured information from conversations such as contact details and business data.

Data collection automatically extracts structured information from conversation transcripts using LLM-powered analysis. This enables you to capture valuable data points without manual processing, improving operational efficiency and data accuracy.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/v6_oVI0xy00?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Data collection analyzes conversation transcripts to identify and extract specific information you define. The extracted data is structured according to your specifications and made available for downstream processing and analysis.

### Supported Data Types

Data collection supports four data types to handle various information formats:

* **String**: Text-based information (names, emails, addresses)
* **Boolean**: True/false values (agreement status, eligibility)
* **Integer**: Whole numbers (quantity, age, ratings)
* **Number**: Decimal numbers (prices, percentages, measurements)

## Configuration

<Steps>
  <Step title="Access data collection settings">
    In the **Analysis** tab of your agent settings, navigate to the **Data collection** section.

    <Frame background="subtle">
      ![Setting up data collection](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1dd7120a0d0236e4b225f1054f17c13956dc5ccc7de275e600eaab9e20604634/assets/images/conversational-ai/collection.gif)
    </Frame>
  </Step>

  <Step title="Add data collection items">
    Click **Add item** to create a new data extraction rule.

    Configure each item with:

    * **Identifier**: Unique name for the data field (e.g., `email`, `customer_rating`)
    * **Data type**: Select from string, boolean, integer, or number
    * **Description**: Detailed instructions on how to extract the data from the transcript

    <Info>
      The description field is passed to the LLM and should be as specific as possible about what to extract and how to format it.
    </Info>

    <Note>
      Data collection items are limited to 40 per agent for Trial and Enterprise plans, and 25 per agent for other plans.
    </Note>
  </Step>

  <Step title="Review extracted data">
    Extracted data appears in your conversation history, allowing you to review what information was captured from each interaction.

    <Frame background="subtle">
      ![Data collection results in conversation history](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/beddd4acf7a431f10b6d6ac602d4ef16604e93bc51040325e185df6517ba3021/assets/images/conversational-ai/collection_result.gif)
    </Frame>
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Writing effective extraction prompts">
    * Be explicit about the expected format (e.g., "email address in the format [user@domain.com](mailto:user@domain.com)")
    * Specify what to do when information is missing or unclear
    * Include examples of valid and invalid data
    * Mention any validation requirements
  </Accordion>

  <Accordion title="Common data collection examples">
    **Contact Information:**

    * `email`: "Extract the customer's email address in standard format ([user@domain.com](mailto:user@domain.com))"
    * `phone_number`: "Extract the customer's phone number including area code"
    * `full_name`: "Extract the customer's complete name as provided"

    **Business Data:**

    * `issue_category`: "Classify the customer's issue into one of: technical, billing, account, or general"
    * `satisfaction_rating`: "Extract any numerical satisfaction rating given by the customer (1-10 scale)"
    * `order_number`: "Extract any order or reference number mentioned by the customer"

    **Behavioral Data:**

    * `was_angry`: "Determine if the customer expressed anger or frustration during the call"
    * `requested_callback`: "Determine if the customer requested a callback or follow-up"
  </Accordion>

  <Accordion title="Handling missing or unclear data">
    When the requested data cannot be found or is ambiguous in the transcript, the extraction will return null or empty values. Consider:

    * Using conditional logic in your applications to handle missing data
    * Creating fallback criteria for incomplete extractions
    * Training agents to consistently gather required information
  </Accordion>
</AccordionGroup>

## Data Type Guidelines

<Tabs>
  <Tab title="String">
    Use for text-based information that doesn't fit other types.

    **Examples:**

    * Customer names
    * Email addresses
    * Product categories
    * Issue descriptions

    **Best practices:**

    * Specify expected format when relevant
    * Include validation requirements
    * Consider standardization needs
  </Tab>

  <Tab title="Boolean">
    Use for yes/no, true/false determinations.

    **Examples:**

    * Customer agreement status
    * Eligibility verification
    * Feature requests
    * Complaint indicators

    **Best practices:**

    * Clearly define what constitutes true vs. false
    * Handle ambiguous responses
    * Consider default values for unclear cases
  </Tab>

  <Tab title="Integer">
    Use for whole number values.

    **Examples:**

    * Customer age
    * Product quantities
    * Rating scores
    * Number of issues

    **Best practices:**

    * Specify valid ranges when applicable
    * Handle non-numeric responses
    * Consider rounding rules if needed
  </Tab>

  <Tab title="Number">
    Use for decimal or floating-point values.

    **Examples:**

    * Monetary amounts
    * Percentages
    * Measurements
    * Calculated scores

    **Best practices:**

    * Specify precision requirements
    * Include currency or unit context
    * Handle different number formats
  </Tab>
</Tabs>

## Use Cases

<CardGroup cols={2}>
  <Card title="Lead Qualification" icon="user-check">
    Extract contact information, qualification criteria, and interest levels from sales conversations.
  </Card>

  <Card title="Customer Intelligence" icon="brain">
    Gather structured data about customer preferences, feedback, and behavior patterns for strategic
    insights.
  </Card>

  <Card title="Support Analytics" icon="chart-line">
    Capture issue categories, resolution details, and satisfaction scores for operational
    improvements.
  </Card>

  <Card title="Compliance Documentation" icon="clipboard-check">
    Extract required disclosures, consents, and regulatory information for audit trails.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Data extraction returning empty values">
    * Verify the data exists in the conversation transcript
    * Check if your extraction prompt is specific enough
    * Ensure the data type matches the expected format
    * Consider if the information was communicated clearly during the conversation
  </Accordion>

  <Accordion title="Inconsistent data formats">
    * Review extraction prompts for format specifications
    * Add validation requirements to prompts
    * Consider post-processing for data standardization
    * Test with various conversation scenarios
  </Accordion>

  <Accordion title="Performance considerations">
    * Each data collection rule adds processing time
    * Complex extraction logic may take longer to evaluate
    * Monitor extraction accuracy vs. speed requirements
    * Optimize prompts for efficiency when possible
  </Accordion>
</AccordionGroup>

<Info>
  Extracted data is available through [Post-call
  Webhooks](/docs/agents-platform/workflows/post-call-webhooks) for integration with CRM systems,
  databases, and analytics platforms.
</Info>


# ElevenAgents dashboard

> Monitor and analyze your agents' performance effortlessly.

## Overview

The Agents Dashboard provides real-time insights into your ElevenLabs agents. It displays performance metrics over customizable time periods. You can review data for individual agents or across your entire workspace.

## Analytics

You can monitor activity over various daily, weekly, and monthly time periods.

<Frame caption="Dashboard view for Last Day" background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8a4120ca3dfe73a5f06a73a91141e270b849a7777d596ffbf0917f5bf89a99cb/assets/images/conversational-ai/lastday.png" alt="Dashboard view showing last day metrics" />
</Frame>

<Frame caption="Dashboard view for Last Month" background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d94a0a810bfd0d0e89e79fd6543e724f7b49ff8ac33cc074eab6aea450d4eb60/assets/images/conversational-ai/lastmonth.png" alt="Dashboard view showing last month metrics" />
</Frame>

The dashboard can be toggled to show different metrics, including: number of calls, average duration, total cost, and average cost.

## Language Breakdown

A key benefit of ElevenLabs Agents is the ability to support multiple languages.
The Language Breakdown section shows the percentage of calls (overall, or per-agent) in each language.

<Frame caption="Language Breakdown" background="subtle">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e8fe67dd25aa16cd748ffb629f099539eab7e133464d4e23243a764e002f23fe/assets/images/conversational-ai/dashboard-language-breakdown.png" alt="Language breakdown showing percentage of calls in each language" />
</Frame>

## Active Calls

At the top left of the dashboard, the current number of active calls is displayed. This real-time counter reflects ongoing sessions for your workspace's agents, and is also accessible via the API.


# Real-time monitoring

> Observe live conversations and send control commands during active calls

Real-time monitoring enables live observation of agent conversations via WebSocket and remote control of active calls. This feature provides real-time visibility into conversation events and allows intervention through control commands.

<Note>
  This is an enterprise-only feature.
</Note>

## Overview

Monitoring sessions stream conversation events in real-time, including transcripts, agent responses, and corrections. You can also send control commands to end calls, transfer to phone numbers, or enable human takeover during active chat conversations.

## WebSocket endpoint

Connect to a live conversation using the monitoring endpoint:

```
wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor
```

Replace `{conversation_id}` with the ID of the conversation you want to monitor.

## Authentication

Authentication requires:

* **API key permissions**: Your API key must have `ElevenLabs Agents Write` scope
* **Workspace access**: You must have `EDITOR` access to the agent's workspace
* **Header format**: Include your API key via the `xi-api-key` header

### Example connection

<CodeBlocks>
  ```javascript
  const ws = new WebSocket('wss://api.elevenlabs.io/v1/convai/conversations/conv_123/monitor', {
    headers: {
      'xi-api-key': 'your_api_key_here',
    },
  });
  ```

  ```python
  import websockets
  import asyncio

  async def monitor_conversation():
      uri = "wss://api.elevenlabs.io/v1/convai/conversations/conv_123/monitor"
      headers = {
          "xi-api-key": "your_api_key_here"
      }

      async with websockets.connect(uri, extra_headers=headers) as websocket:
          # Connection established
          pass
  ```
</CodeBlocks>

## Configuration

Before monitoring conversations, enable the feature in your agent's settings:

<Steps>
  ### Navigate to agent settings

  Open your agent's configuration page in the dashboard.

  ### Enable monitoring

  In the Advanced settings panel, toggle the "Monitoring" option.

  <Frame background="subtle">
    ![Monitoring toggle in agent settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1a4b5507a39ddf6a517772b8c01ede5f7d12429175fdf89e04c8ba910f646f8e/assets/images/agents/realtime-monitoring-toggle.png)
  </Frame>

  ### Select events

  Choose which events you want to monitor. See [Client Events](/docs/agents-platform/customization/events/client-events) for a full list of available events.

  <Warning>
    The following events cannot be monitored: VAD scores, turn probability metrics, and pings.
  </Warning>
</Steps>

<Info>
  The conversation must be active before you can connect to monitor it. You cannot monitor a
  conversation before it begins.
</Info>

## Control commands

Send JSON commands through the WebSocket to control the conversation:

<AccordionGroup>
  <Accordion title="End call">
    Terminate the active conversation immediately.

    <CodeBlocks>
      ```javascript
      // End the active conversation
      ws.send(JSON.stringify({
        command_type: "end_call"
      }));
      ```

      ```python
      import json

      # End the active conversation
      await websocket.send(json.dumps({
          "command_type": "end_call"
      }))
      ```
    </CodeBlocks>
  </Accordion>

  <Accordion title="Transfer to phone number">
    Transfer the call to a specified phone number.

    <CodeBlocks>
      ```javascript
      // Transfer to a phone number
      ws.send(JSON.stringify({
        command_type: "transfer_to_number",
        parameters: {
          phone_number: "+1234567890"
        }
      }));
      ```

      ```python
      import json

      # Transfer to a phone number
      await websocket.send(json.dumps({
          "command_type": "transfer_to_number",
          "parameters": {
              "phone_number": "+1234567890"
          }
      }))
      ```
    </CodeBlocks>

    <Note>
      The 

      `transfer_to_number`

       system tool must already be configured in the agent.
    </Note>
  </Accordion>

  <Accordion title="Enable human takeover">
    Switch from AI agent to human operator mode for chat conversations.

    <CodeBlocks>
      ```javascript
      // Enable human takeover
      ws.send(JSON.stringify({
        command_type: "enable_human_takeover"
      }));
      ```

      ```python
      import json

      # Enable human takeover
      await websocket.send(json.dumps({
          "command_type": "enable_human_takeover"
      }))
      ```
    </CodeBlocks>
  </Accordion>

  <Accordion title="Send message as human">
    Send a message to the user as a human operator in chat conversations.

    <CodeBlocks>
      ```javascript
      // Send a message as a human operator
      ws.send(JSON.stringify({
        command_type: "send_human_message",
        parameters: {
          text: "How can I help you?"
        }
      }));
      ```

      ```python
      import json

      # Send a message as a human operator
      await websocket.send(json.dumps({
          "command_type": "send_human_message",
          "parameters": {
              "text": "How can I help you?"
          }
      }))
      ```
    </CodeBlocks>
  </Accordion>

  <Accordion title="Disable human takeover">
    Return control from human operator back to the AI agent.

    <CodeBlocks>
      ```javascript
      // Disable human takeover and return to AI
      ws.send(JSON.stringify({
        command_type: "disable_human_takeover"
      }));
      ```

      ```python
      import json

      # Disable human takeover and return to AI
      await websocket.send(json.dumps({
          "command_type": "disable_human_takeover"
      }))
      ```
    </CodeBlocks>
  </Accordion>
</AccordionGroup>

## Use cases

Real-time monitoring enables several operational scenarios:

<CardGroup cols={2}>
  <Card title="Quality assurance" icon="clipboard-check">
    Monitor agent conversations in real-time to ensure quality standards and identify training
    opportunities.
  </Card>

  <Card title="Human escalation" icon="user-headset">
    Detect conversations requiring human intervention and seamlessly take over from the AI agent.
  </Card>

  <Card title="Analytics dashboards" icon="chart-line">
    Build real-time monitoring dashboards that aggregate conversation metrics and performance
    indicators.
  </Card>

  <Card title="Call center oversight" icon="headset">
    Supervise multiple agent conversations simultaneously and intervene when necessary.
  </Card>

  <Card title="Automated intervention" icon="wand-magic-sparkles">
    Implement automated systems that analyze conversation content and trigger actions based on
    specific conditions.
  </Card>

  <Card title="Training and coaching" icon="graduation-cap">
    Use live conversations as training material and provide real-time feedback to improve agent
    performance.
  </Card>
</CardGroup>

## Limitations

<AccordionGroup>
  <Accordion title="Audio data not available">
    The monitoring endpoint streams only text events and metadata. Raw audio data is not included in
    monitoring events.
  </Accordion>

  <Accordion title="Historical event limit">
    Only approximately the last 100 events are cached and available when connecting to an active
    conversation. Earlier events cannot be retrieved.
  </Accordion>

  <Accordion title="Event filtering restrictions">
    VAD scores, turn probability metrics, and ping events cannot be monitored when custom event
    selection is enabled.
  </Accordion>

  <Accordion title="Connection timing">
    You must connect after the conversation has started. The monitoring endpoint cannot be used
    before conversation initiation.
  </Accordion>

  <Accordion title="Permissions required">
    API keys must have `ElevenLabs Agents Write` scope, and you must have `EDITOR` workspace access
    to monitor conversations.
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup cols={2}>
  <Card title="Post-call Webhooks" icon="bell-ring" href="/docs/agents-platform/workflows/post-call-webhooks">
    Receive conversation data and analysis after calls complete.
  </Card>

  <Card title="Agent Analysis" icon="chart-line-up" href="/docs/agents-platform/customization/agent-analysis">
    Configure success evaluation and data collection for conversations.
  </Card>

  <Card title="Client Events" icon="cloud-arrow-down" href="/docs/agents-platform/customization/events/client-events">
    Understand events received during conversational applications.
  </Card>

  <Card title="WebSocket API" icon="spider-web" href="/docs/agents-platform/libraries/web-sockets">
    Learn about the WebSocket API for real-time conversations.
  </Card>
</CardGroup>


# Privacy

> Manage how your agent handles data storage and privacy.

Privacy settings give you fine-grained control over your data. You can manage both call audio recordings and conversation data retention to meet your compliance and privacy requirements.

<CardGroup cols={2}>
  <Card title="Retention" icon="database" href="/docs/agents-platform/customization/privacy/retention">
    Configure how long conversation transcripts and audio recordings are retained.
  </Card>

  <Card title="Audio Saving" icon="microphone" href="/docs/agents-platform/customization/privacy/audio-saving">
    Control whether call audio recordings are retained.
  </Card>
</CardGroup>

## Retention

Retention settings control the duration for which conversation transcripts and audio recordings are stored.

For detailed instructions, see our [Retention](/docs/agents-platform/customization/privacy/retention) page.

## Audio Saving

Audio Saving settings determine if call audio recordings are stored. Adjust this feature based on your privacy and data retention needs.

For detailed instructions, see our [Audio Saving](/docs/agents-platform/customization/privacy/audio-saving) page.

## Recommended Privacy Configurations

<AccordionGroup>
  <Accordion title="Maximum Privacy">
    Disable audio saving and set retention to 0 days for immediate deletion of data.
  </Accordion>

  <Accordion title="Balanced Privacy">
    Enable audio saving for critical interactions while setting a moderate retention period.
  </Accordion>

  <Accordion title="Compliance Focus">
    Enable audio saving and configure retention settings to adhere to regulatory requirements such
    as GDPR and HIPAA. For HIPAA compliance, we recommend enabling audio saving and setting a
    retention period of at least 6 years. For GDPR, retention periods should align with your data
    processing purposes.
  </Accordion>
</AccordionGroup>


# Retention

> Control how long your agent retains conversation history and recordings.

**Retention** settings allow you to configure how long your conversational agent stores conversation transcripts and audio recordings. These settings help you comply with data privacy regulations.

## Overview

By default, ElevenLabs retains conversation data for 2 years. You can modify this period to:

* Any number of days (e.g., 30, 90, 365)
* Unlimited retention by setting the value to -1
* Scheduled deletion by setting the value to 0

The retention settings apply separately to:

* **Conversation transcripts**: Text records of all interactions
* **Audio recordings**: Voice recordings from both the user and agent

<Info>
  For GDPR compliance, we recommend setting retention periods that align with your data processing
  purposes. For HIPAA compliance, retain records for a minimum of 6 years.
</Info>

## Modifying retention settings

### Prerequisites

* An [ElevenLabs account](https://elevenlabs.io)
* A configured ElevenLabs Conversational Agent ([create one here](/docs/agents-platform/quickstart))

Follow these steps to update your retention settings:

<Steps>
  <Step title="Access retention settings">
    Navigate to your agent's settings and select the "Advanced" tab. The retention settings are located in the "Data Retention" section.

    <Frame background="subtle">
      ![Enable overrides](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/39019a60151b8d999d5e1719e1553508a91c3bf7a34e6f5729ea2942c3dc4d57/assets/images/conversational-ai/retention.png)
    </Frame>
  </Step>

  <Step title="Update retention period">
    1. Enter the desired retention period in days
    2. Choose whether to apply changes to existing data
    3. Click "Save" to confirm changes

    <Frame background="subtle">
      ![Enable overrides](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a5d069a0957ee06672aab4a8784362a72ed7d3f055d548eb54b32998ec246aad/assets/images/conversational-ai/retention-apply-existing.png)
    </Frame>

    When modifying retention settings, you'll have the option to apply the new retention period to existing conversation data or only to new conversations going forward.
  </Step>
</Steps>

<Warning>
  Reducing the retention period may result in immediate deletion of data older than the new
  retention period if you choose to apply changes to existing data.
</Warning>


# Audio saving

> Control whether call audio recordings are retained.

**Audio Saving** settings allow you to choose whether recordings of your calls are retained in your call history, on a per-agent basis. This control gives you flexibility over data storage and privacy.

## Overview

By default, audio recordings are enabled. You can modify this setting to:

* **Enable audio saving**: Save call audio for later review.
* **Disable audio saving**: Omit audio recordings from your call history.

<Info>
  Disabling audio saving enhances privacy but limits the ability to review calls. However,
  transcripts can still be viewed. To modify transcript retention settings, please refer to the
  [retention](/docs/agents-platform/customization/privacy/retention) documentation.
</Info>

## Modifying Audio Saving Settings

### Prerequisites

* A configured [ElevenLabs Conversational Agent](/docs/agents-platform/quickstart)

Follow these steps to update your audio saving preference:

<Steps>
  <Step title="Access audio saving settings">
    Find your agent in the ElevenAgents [page](https://elevenlabs.io/app/agents/agents) and select
    the "Advanced" tab. The audio saving control is located in the "Privacy Settings" section.

    <Frame background="subtle">
      ![Disable audio saving option](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e2f7d92f9128bace5d992e76aa500da7e1bc62d22d423841b774c1e20fcaf891/assets/images/conversational-ai/no-audio-setting.png)
    </Frame>
  </Step>

  <Step title="Choose saving option">
    Toggle the control to enable or disable audio saving and click save to confirm your selection.
  </Step>

  <Step title="Review call history">
    When audio saving is enabled, calls in the call history allow you to review the audio.

    <Frame background="subtle">
      ![Call with audio saved](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/871a28d699f54774c3e2695091e9af04948e236afded7807c27ea73bc2a8f71f/assets/images/conversational-ai/audio.png)
    </Frame>

    When audio saving is disabled, calls in the call history do not include audio.

    <Frame background="subtle">
      ![Call without audio saved](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5dffbe46545eda166d48328b21f63ff0a6d3a0a8b05224213307da426ba6e47e/assets/images/conversational-ai/no-audio.png)
    </Frame>
  </Step>
</Steps>

<Warning>
  Disabling audio saving will prevent new call audio recordings from being stored. Existing
  recordings will remain until deleted via [retention
  settings](/docs/agents-platform/customization/privacy/retention).
</Warning>


# Optimizing LLM costs

> Practical strategies to reduce LLM inference expenses on the ElevenLabs platform.

## Overview

Managing Large Language Model (LLM) inference costs is essential for developing sustainable AI applications. This guide outlines key strategies to optimize expenditure on the ElevenLabs platform by effectively utilizing its features. For detailed model capabilities and pricing, refer to our main [LLM documentation](/docs/agents-platform/customization/llm).

<Note>
  ElevenLabs supports reducing costs by reducing inference of the models during periods of silence.
  These periods are billed at 5% of the usual per minute rate. See [the ElevenAgents overview
  page](/docs/agents-platform/overview#pricing-during-silent-periods) for more details.
</Note>

## Understanding inference costs

LLM inference costs on our platform are primarily influenced by:

* **Input tokens**: The amount of data processed from your prompt, including user queries, system instructions, and any contextual data.
* **Output tokens**: The number of tokens generated by the LLM in its response.
* **Model choice**: Different LLMs have varying per-token pricing. More powerful models generally incur higher costs.

Monitoring your usage via the ElevenLabs dashboard or API is crucial for identifying areas for cost reduction.

## Strategic model selection

Choosing the most appropriate LLM is a primary factor in cost efficiency.

* **Right-sizing**: Select the least complex (and typically less expensive) model that can reliably perform your specific task. Avoid using high-cost models for simple operations. For instance, models like Google's `gemini-2.0-flash` offer highly competitive pricing for many common tasks. Always cross-reference with the full [Supported LLMs list](/docs/agents-platform/customization/llm#supported-llms) for the latest pricing and capabilities.
* **Experimentation**: Test various models for your tasks, comparing output quality against incurred costs. Consider language support, context window needs, and specialized skills.

## Prompt optimization

Prompt engineering is a powerful technique for reducing token consumption and associated costs. By crafting clear, concise, and unambiguous system prompts, you can guide the model to produce more efficient responses. Eliminate redundant wording and unnecessary context that might inflate your token count. Consider explicitly instructing the model on your desired output length—for example, by adding phrases like "Limit your response to two sentences" or "Provide a brief summary." These simple directives can significantly reduce the number of output tokens while maintaining the quality and relevance of the generated content.

**Modular design**: For complex conversational flows, leverage [agent-agent transfer](/docs/agents-platform/customization/tools/system-tools/agent-transfer). This allows you to break down a single, large system prompt into multiple, smaller, and more specialized prompts, each handled by a different agent. This significantly reduces the token count per interaction by loading only the contextually relevant prompt for the current stage of the conversation, rather than a comprehensive prompt designed for all possibilities.

## Leveraging knowledge and retrieval

For applications requiring access to large information volumes, Retrieval Augmented Generation (RAG) and a well-maintained knowledge base are key.

* **Efficient RAG**:
  * RAG reduces input tokens by providing the LLM with only relevant snippets from your [Knowledge Base](/docs/agents-platform/customization/knowledge-base), instead of including extensive data in the prompt.
  * Optimize the retriever to fetch only the most pertinent "chunks" of information.
  * Fine-tune chunk size and overlap for a balance between context and token count.
  * Learn more about implementing [RAG](/docs/agents-platform/customization/knowledge-base/rag).
* **Context size**:
  * Ensure your [Knowledge Base](/docs/agents-platform/customization/knowledge-base) contains accurate, up-to-date, and relevant information.
  * Well-structured content improves retrieval precision and reduces token usage from irrelevant context.

## Intelligent tool utilization

Using [Server Tools](/docs/agents-platform/customization/tools/server-tools) allows LLMs to delegate tasks to external APIs or custom code, which can be more cost-effective.

* **Task offloading**: Identify deterministic tasks, those requiring real-time data, complex calculations, or API interactions (e.g., database lookups, external service calls).
* **Orchestration**: The LLM acts as an orchestrator, making structured tool calls. This is often far more token-efficient than attempting complex tasks via prompting alone.
* **Tool descriptions**: Provide clear, concise descriptions for each tool, enabling the LLM to use them efficiently and accurately.

## Checklist

Consider applying these techniques to reduce cost:

| Feature           | Cost impact                                              | Action items                                                                                                                                                        |
| :---------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| LLM choice        | Reduces per-token cost                                   | Select the smallest, most economical model that reliably performs the task. Experiment and compare cost vs. quality.                                                |
| Custom LLMs       | Potentially lower inference cost for specialized tasks   | Evaluate for high-volume, specific tasks; fine-tune on proprietary data to create smaller, efficient models.                                                        |
| System prompts    | Reduces input & output tokens, guides model behavior     | Be concise, clear, and specific. Instruct on desired output format and length (e.g., "be brief," "use JSON").                                                       |
| User prompts      | Reduces input tokens                                     | Encourage specific queries; use few-shot examples strategically; summarize or select relevant history.                                                              |
| Output control    | Reduces output tokens                                    | Prompt for summaries or key info; use `max_tokens` cautiously; iterate on prompts to achieve natural conciseness.                                                   |
| RAG               | Reduces input tokens by avoiding large context in prompt | Optimize retriever for relevance; fine-tune chunk size/overlap; ensure high-quality embeddings and search algorithms.                                               |
| Knowledge base    | Improves RAG efficiency, reducing irrelevant tokens      | Curate regularly; remove outdated info; ensure good structure, metadata, and tagging for precise retrieval.                                                         |
| Tools (functions) | Avoids LLM calls for specific tasks; reduces tokens      | Delegate deterministic, calculation-heavy, or external API tasks to tools. Design clear tool descriptions for the LLM.                                              |
| Agent transfer    | Enables use of cheaper models for simpler parts of tasks | Use simpler/cheaper agents for initial triage/FAQs; transfer to capable agents only when needed; decompose large prompts into smaller prompts across various agents |

<Note title="Conversation history management">
  For stateful conversations, rather than passing in multiple conversation transcripts as a part of
  the system prompt, implement history summarization or sliding window techniques to keep context
  lean. This can be particularly effective when building consumer applications and can often be
  managed upon receiving a post-call webhook.
</Note>

<Tip>
  Continuously monitor your LLM usage and costs. Regularly review and refine your prompts, RAG
  configurations, and tool integrations to ensure ongoing cost-effectiveness.
</Tip>


# ElevenLabs CLI

> Manage your voice agents as code from your command line.

## Overview

The ElevenLabs CLI allows you to access your ElevenLabs agents from your terminal, unlocking new ways to manage them:

* Store agents as code in your version control system
* Set up CI/CD integration to automatically deploy your agents
* Let your coding agent access and manage your voice agents

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [complete source code and contribute on GitHub](https://github.com/elevenlabs/cli).
</Tip>

## Installation

The CLI requires Node.js version 16.0.0 or higher.

<CodeBlocks>
  ```bash title="npm"
  npm install -g @elevenlabs/cli
  ```

  ```bash title="pnpm"
  pnpm add -g @elevenlabs/cli
  ```

  ```bash title="yarn"
  yarn global add @elevenlabs/cli
  ```
</CodeBlocks>

After installation, the `elevenlabs` command will be available globally in your terminal.

## Quick start

<Steps>
  ### Initialize a new project

  ```bash
  elevenlabs agents init
  ```

  This creates the project structure with configuration directories and registry files.

  ### Authenticate with ElevenLabs

  ```bash
  elevenlabs auth login
  ```

  Enter your ElevenLabs API key when prompted. The CLI will verify the key and store it securely.

  ### Create your first agent

  ```bash
  elevenlabs agents add "My Assistant" --template assistant
  ```

  This creates a new agent configuration using the assistant template.

  ### Push to ElevenLabs platform

  ```bash
  elevenlabs agents push
  ```

  This uploads your local agent configuration to the ElevenLabs platform.
</Steps>

## Project structure

The CLI creates a structured project directory:

```
your_project/
├── agents.json              # Central agent configuration registry
├── tools.json               # Tool definitions registry
├── tests.json               # Test definitions registry
├── agent_configs/           # Agent configuration files
├── tool_configs/            # Tool configuration files
└── test_configs/            # Test configuration files
```

## Authentication

The CLI stores API keys in `~/.agents/api_keys.json` file with restricted permissions (600).

### Authentication commands

<CodeBlocks>
  ```bash title="Login"
  elevenlabs auth login
  ```

  ```bash title="Check login status"
  elevenlabs auth whoami
  ```

  ```bash title="Logout"
  elevenlabs auth logout
  ```
</CodeBlocks>

## Agent management

### Creating agents

Create agents using pre-built templates:

```bash
elevenlabs agents add "Agent Name" [options]
```

**Options:**

* `--template <type>`: Choose from available templates (default: default)
* `--skip-upload`: Create locally without uploading to platform

**Example:**

```bash
elevenlabs agents add "Customer Support Bot" --template customer-service
```

### Templates

The CLI provides six pre-built templates for common use cases:

<AccordionGroup>
  <Accordion title="default">
    Complete configuration with all available fields, sensible defaults, full voice/text support, widget customization, and evaluation criteria.
  </Accordion>

  <Accordion title="minimal">
    Essential fields only including basic prompt, language, TTS, and conversation settings.
  </Accordion>

  <Accordion title="voice-only">
    Optimized for voice interactions with disabled text input and advanced voice settings.
  </Accordion>

  <Accordion title="text-only">
    Text-focused conversations with disabled voice features.
  </Accordion>

  <Accordion title="customer-service">
    Professional empathetic prompts, low temperature (0.1), 30-minute duration, and evaluation
    criteria.
  </Accordion>

  <Accordion title="assistant">
    General-purpose AI assistant with balanced creativity (temperature 0.3) and versatile voice/text support.
  </Accordion>
</AccordionGroup>

### Template commands

<CodeBlocks>
  ```bash title="List available templates"
  elevenlabs agents templates list
  ```

  ```bash title="Show template configuration"
  elevenlabs agents templates show <template>
  ```
</CodeBlocks>

### Synchronization

Keep your local configurations synchronized with the ElevenLabs platform:

<CodeBlocks>
  ```bash title="Push all agents"
  elevenlabs agents push
  ```

  ```bash title="Preview changes (dry run)"
  elevenlabs agents push --dry-run
  ```
</CodeBlocks>

### Status and monitoring

<CodeBlocks>
  ```bash title="Check agent status"
  elevenlabs agents status
  ```
</CodeBlocks>

### Import and export

<CodeBlocks>
  ```bash title="Import existing agents"
  elevenlabs agents pull
  ```

  ```bash title="Import specific agent"
  elevenlabs agents pull --agent <agent_id>
  ```

  ```bash title="Update agents"
  elevenlabs agents pull --update
  ```

  ```bash title="List all agents"
  elevenlabs agents list
  ```
</CodeBlocks>

<Note>
  By default, `elevenlabs agents pull` skips agents that already exist locally. Use the `--update`
  flag to override local configurations with remote changes made in the browser or via the API.
</Note>

## Tool management

The CLI supports two types of tools for extending agent capabilities:

### Webhook tools

HTTP API integrations with authentication and timeout configuration:

```bash
elevenlabs agents tools add "API Integration" --type "webhook" --config-path ./config.json
```

### Client tools

Direct client-side integrations:

```bash
elevenlabs agents tools add "Client Function" --type "client" --config-path ./config.json
```

## Widget generation

Generate HTML embed code for web integration:

```bash
elevenlabs agents widget <agent_id>
```

This outputs HTML code like:

```html
<elevenlabs-convai agent-id="agent_id_here"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async></script>
```

## Configuration files

### Agent configuration structure

Each agent configuration includes:

```json
{
  "name": "Agent Name",
  "conversation_config": {
    "agent": {
      "prompt": "You are a helpful assistant...",
      "llm": {
        "model": "eleven-multilingual-v1",
        "temperature": 0.3
      },
      "language": "en",
      "tools": []
    },
    "tts": {
      "model": "eleven-multilingual-v1",
      "voice_id": "pNInz6obpgDQGcFmaJgB",
      "audio_format": {
        "format": "pcm",
        "sample_rate": 44100
      }
    },
    "asr": {
      "model": "nova-2-general",
      "language": "auto"
    },
    "conversation": {
      "max_duration_seconds": 1800,
      "text_only": false,
      "client_events": []
    }
  },
  "platform_settings": {
    "widget": {
      "conversation_starters": [],
      "branding": {}
    }
  },
  "tags": ["environment:dev"]
}
```

### CI/CD pipeline integration

```yml
# In your GitHub Actions workflow
- name: Deploy ElevenAgents agents
  run: |
    npm install -g @elevenlabs/cli
    export ELEVENLABS_API_KEY=${{ secrets.ELEVENLABS_API_KEY }}
    elevenlabs agents push --dry-run  # Preview changes
    elevenlabs agents push            # Deploy
    elevenlabs agents status          # Verify deployment
```


# Events

> Understand real-time communication events exchanged between client and server in ElevenLabs Agents

## Overview

Events are the foundation of real-time communication in ElevenLabs Agents applications using WebSockets.
They facilitate the exchange of information like audio streams, transcriptions, agent responses, and contextual updates between the client application and the server infrastructure.

Understanding these events is crucial for building responsive and interactive conversational experiences.

Events are broken down into two categories:

<CardGroup cols={2}>
  <Card title="Client Events (Server-to-Client)" href="/agents-platform/customization/events/client-events" icon="cloud-arrow-down">
    Events sent from the server to the client, delivering audio, transcripts, agent messages, and
    system signals.
  </Card>

  <Card title="Client-to-Server Events" href="/agents-platform/customization/events/client-to-server-events" icon="cloud-arrow-up">
    Events sent from the client to the server, providing contextual updates or responding to server
    requests.
  </Card>
</CardGroup>


# Client events

> Understand and handle real-time events received by the client during conversational applications.

**Client events** are system-level events sent from the server to the client that facilitate real-time communication. These events deliver audio, transcription, agent responses, and other critical information to the client application.

<Note>
  For information on events you can send from the client to the server, see the [Client-to-server
  events](/docs/agents-platform/customization/events/client-to-server-events) documentation.
</Note>

## Overview

Client events are essential for maintaining the real-time nature of conversations. They provide everything from initialization metadata to processed audio and agent responses.

<Info>
  These events are part of the WebSocket communication protocol and are automatically handled by our
  SDKs. Understanding them is crucial for advanced implementations and debugging.
</Info>

## Client event types

<AccordionGroup>
  <Accordion title="conversation_initiation_metadata">
    * Automatically sent when starting a conversation
    * Initializes conversation settings and parameters

    ```javascript
    // Example initialization metadata
    {
      "type": "conversation_initiation_metadata",
      "conversation_initiation_metadata_event": {
        "conversation_id": "conv_123",
        "agent_output_audio_format": "pcm_44100",  // TTS output format
        "user_input_audio_format": "pcm_16000"    // ASR input format
      }
    }
    ```
  </Accordion>

  <Accordion title="ping">
    * Health check event requiring immediate response
    * Automatically handled by SDK
    * Used to maintain WebSocket connection

      ```javascript
      // Example ping event structure
      {
        "ping_event": {
          "event_id": 123456,
          "ping_ms": 50  // Optional, estimated latency in milliseconds
        },
        "type": "ping"
      }
      ```

      ```javascript
      // Example ping handler
      websocket.on('ping', () => {
        websocket.send('pong');
      });
      ```
  </Accordion>

  <Accordion title="audio">
    * Contains base64 encoded audio for playback
    * Includes numeric event ID for tracking and sequencing
    * Handles voice output streaming
    * Includes alignment data with character-level timing information

    <Note>
      Over WebRTC connections, the `audio` event is not sent as audio is handled directly by LiveKit.
    </Note>

    ```javascript
    // Example audio event structure
    {
      "audio_event": {
        "audio_base_64": "base64_encoded_audio_string",
        "event_id": 12345,
        "alignment": {  // Character-level timing data
          "chars": ["H", "e", "l", "l", "o"],
          "char_durations_ms": [50, 30, 40, 40, 60],
          "char_start_times_ms": [0, 50, 80, 120, 160]
        }
      },
      "type": "audio"
    }
    ```

    ```javascript
    // Example audio event handler
    websocket.on('audio', (event) => {
      const { audio_event } = event;
      const { audio_base_64, event_id, alignment } = audio_event;
      audioPlayer.play(audio_base_64);

      // Use alignment data for synchronized text display
      const { chars, char_start_times_ms } = alignment;
      chars.forEach((char, i) => {
        setTimeout(() => highlightCharacter(char, i), char_start_times_ms[i]);
      });
    });
    ```
  </Accordion>

  <Accordion title="user_transcript">
    * Contains finalized speech-to-text results
    * Represents complete user utterances
    * Used for conversation history

    ```javascript
    // Example transcript event structure
    {
      "type": "user_transcript",
      "user_transcription_event": {
        "user_transcript": "Hello, how can you help me today?"
      }
    }
    ```

    ```javascript
    // Example transcript handler
    websocket.on('user_transcript', (event) => {
      const { user_transcription_event } = event;
      const { user_transcript } = user_transcription_event;
      updateConversationHistory(user_transcript);
    });
    ```
  </Accordion>

  <Accordion title="agent_response">
    * Contains complete agent message
    * Sent with first audio chunk
    * Used for display and history

    ```javascript
    // Example response event structure
    {
      "type": "agent_response",
      "agent_response_event": {
        "agent_response": "Hello, how can I assist you today?"
      }
    }
    ```

    ```javascript
    // Example response handler
    websocket.on('agent_response', (event) => {
      const { agent_response_event } = event;
      const { agent_response } = agent_response_event;
      displayAgentMessage(agent_response);
    });
    ```
  </Accordion>

  <Accordion title="agent_response_correction">
    * Contains truncated response after interruption
      * Updates displayed message
      * Maintains conversation accuracy

    ```javascript
    // Example response correction event structure
    {
      "type": "agent_response_correction",
      "agent_response_correction_event": {
        "original_agent_response": "Let me tell you about the complete history...",
        "corrected_agent_response": "Let me tell you about..."  // Truncated after interruption
      }
    }
    ```

    ```javascript
    // Example response correction handler
    websocket.on('agent_response_correction', (event) => {
      const { agent_response_correction_event } = event;
      const { corrected_agent_response } = agent_response_correction_event;
      displayAgentMessage(corrected_agent_response);
    });
    ```
  </Accordion>

  <Accordion title="client_tool_call">
    * Represents a function call the agent wants the client to execute
    * Contains tool name, tool call ID, and parameters
    * Requires client-side execution of the function and sending the result back to the server

    <Info>
      If you are using the SDK, callbacks are provided to handle sending the result back to the server.
    </Info>

    ```javascript
    // Example tool call event structure
    {
      "type": "client_tool_call",
      "client_tool_call": {
        "tool_name": "search_database",
        "tool_call_id": "call_123456",
        "parameters": {
          "query": "user information",
          "filters": {
            "date": "2024-01-01"
          }
        }
      }
    }
    ```

    ```javascript
    // Example tool call handler
    websocket.on('client_tool_call', async (event) => {
      const { client_tool_call } = event;
      const { tool_name, tool_call_id, parameters } = client_tool_call;

      try {
        const result = await executeClientTool(tool_name, parameters);
        // Send success response back to continue conversation
        websocket.send({
          type: "client_tool_result",
          tool_call_id: tool_call_id,
          result: result,
          is_error: false
        });
      } catch (error) {
        // Send error response if tool execution fails
        websocket.send({
          type: "client_tool_result",
          tool_call_id: tool_call_id,
          result: error.message,
          is_error: true
        });
      }
    });
    ```
  </Accordion>

  <Accordion title="agent_tool_response">
    * Indicates when the agent has executed a tool function
    * Contains tool metadata and execution status
    * Provides visibility into agent tool usage during conversations

    ```javascript
    // Example agent tool response event structure
    {
      "type": "agent_tool_response",
      "agent_tool_response": {
        "tool_name": "skip_turn",
        "tool_call_id": "skip_turn_c82ca55355c840bab193effb9a7e8101",
        "tool_type": "system",
        "is_error": false
      }
    }
    ```

    ```javascript
    // Example agent tool response handler
    websocket.on('agent_tool_response', (event) => {
      const { agent_tool_response } = event;
      const { tool_name, tool_call_id, tool_type, is_error } = agent_tool_response;

      if (is_error) {
        console.error(`Agent tool ${tool_name} failed:`, tool_call_id);
      } else {
        console.log(`Agent executed ${tool_type} tool: ${tool_name}`);
      }
    });
    ```
  </Accordion>

  <Accordion title="vad_score">
    * Voice Activity Detection score event
    * Indicates the probability that the user is speaking
    * Values range from 0 to 1, where higher values indicate higher confidence of speech

    ```javascript
    // Example VAD score event
    {
      "type": "vad_score",
      "vad_score_event": {
        "vad_score": 0.95
      }
    }
    ```
  </Accordion>

  <Accordion title="mcp_tool_call">
    * Indicates when the agent has executed a MCP tool function
    * Contains tool name, tool call ID, and parameters
    * Called with one of four states: `loading`, `awaiting_approval`, `success` and `failure`.

    ```javascript
    {
      "type": "mcp_tool_call",
      "mcp_tool_call": {
        "service_id": "xJ8kP2nQ7sL9mW4vR6tY",
        "tool_call_id": "call_123456",
        "tool_name": "search_database",
        "tool_description": "Search the database for user information",
        "parameters": {
          "query": "user information",
        },
        "timestamp": "2024-09-30T14:23:45.123456+00:00",
        "state": "loading",
        "approval_timeout_secs": 10
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Event flow

Here's a typical sequence of events during a conversation:

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Server->>Client: conversation_initiation_metadata
    Note over Client,Server: Connection established
    Server->>Client: ping
    Client->>Server: pong
    Server->>Client: audio
    Note over Client: Playing audio
    Note over Client: User responds
    Server->>Client: user_transcript
    Server->>Client: audio
    Server->>Client: agent_response
    Server->>Client: client_tool_call
    Note over Client: Client tool runs
    Client->>Server: client_tool_result
    Server->>Client: audio
    Server->>Client: agent_response
    Note over Client: Playing audio
    Note over Client: Interruption detected
    Server->>Client: agent_response_correction

```

### Best practices

1. **Error handling**

   * Implement proper error handling for each event type
   * Log important events for debugging
   * Handle connection interruptions gracefully

2. **Audio management**

   * Buffer audio chunks appropriately
   * Implement proper cleanup on interruption
   * Handle audio resource management

3. **Connection management**

   * Respond to PING events promptly
   * Implement reconnection logic
   * Monitor connection health

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection issues">
    * Ensure proper WebSocket connection
    * Check PING/PONG responses
    * Verify API credentials
  </Accordion>

  <Accordion title="Audio problems">
    * Check audio chunk handling
    * Verify audio format compatibility
    * Monitor memory usage
  </Accordion>

  <Accordion title="Event handling">
    * Log all events for debugging
    * Implement error boundaries
    * Check event handler registration
  </Accordion>
</AccordionGroup>

<Info>
  For detailed implementation examples, check our [SDK
  documentation](/docs/agents-platform/libraries/python).
</Info>


# Client to server events

> Send contextual information from the client to enhance conversational applications in real-time.

**Client-to-server events** are messages that your application proactively sends to the server to provide additional context during conversations. These events enable you to enhance the conversation with relevant information without interrupting the conversational flow.

<Note>
  For information on events the server sends to the client, see the [Client
  events](/docs/agents-platform/customization/events/client-events) documentation.
</Note>

## Overview

Your application can send contextual information to the server to improve conversation quality and relevance at any point during the conversation. This does not have to be in response to a client event received from the server. This is particularly useful for sharing UI state, user actions, or other environmental data that may not be directly communicated through voice.

<Info>
  While our SDKs provide helper methods for sending these events, understanding the underlying
  protocol is valuable for custom implementations and advanced use cases.
</Info>

## Event types

### Contextual updates

Contextual updates allow your application to send non-interrupting background information to the conversation.

**Key characteristics:**

* Updates are incorporated as background information in the conversation.
* Does not interrupt the current conversation flow.
* Useful for sending UI state, user actions, or environmental data.

```javascript
// Contextual update event structure
{
  "type": "contextual_update",
  "text": "User appears to be looking at pricing page"
}
```

```javascript
// Example sending contextual updates
function sendContextUpdate(information) {
  websocket.send(
    JSON.stringify({
      type: 'contextual_update',
      text: information,
    })
  );
}

// Usage examples
sendContextUpdate('Customer status: Premium tier');
sendContextUpdate('User navigated to Help section');
sendContextUpdate('Shopping cart contains 3 items');
```

### User messages

User messages allow you to send text directly to the conversation as if the user had spoken it. This is useful for text-based interactions or when you want to inject specific text into the conversation flow.

**Key characteristics:**

* Text is processed as user input to the conversation.
* Triggers the same response flow as spoken user input.
* Useful for text-based interfaces or programmatic user input.

```javascript
// User message event structure
{
  "type": "user_message",
  "text": "I would like to upgrade my account"
}
```

```javascript
// Example sending user messages
function sendUserMessage(text) {
  websocket.send(
    JSON.stringify({
      type: 'user_message',
      text: text,
    })
  );
}

// Usage examples
sendUserMessage('I need help with billing');
sendUserMessage('What are your pricing options?');
sendUserMessage('Cancel my subscription');
```

### User activity

User activity events serve as indicators to prevent interrupts from the agent.

**Key characteristics:**

* Resets the turn timeout timer.
* Does not affect conversation content or flow.
* Useful for maintaining long-running conversations during periods of silence.

```javascript
// User activity event structure
{
  "type": "user_activity"
}
```

```javascript
// Example sending user activity
function sendUserActivity() {
  websocket.send(
    JSON.stringify({
      type: 'user_activity',
    })
  );
}

// Usage example - send activity ping every 30 seconds
setInterval(sendUserActivity, 30000);
```

## Best practices

1. **Contextual updates**

   * Send relevant but concise contextual information.
   * Avoid overwhelming the LLM with too many updates.
   * Focus on information that impacts the conversation flow or is important context from activity in a UI not accessible to the voice agent.

2. **User messages**

   * Use for text-based user input when audio is not available or appropriate.
   * Ensure text content is clear and well-formatted.
   * Consider the conversation context when injecting programmatic messages.

3. **User activity**

   * Send activity pings during periods of user interaction to maintain session.
   * Use reasonable intervals (e.g., 30-60 seconds) to avoid unnecessary network traffic.
   * Implement activity detection based on actual user engagement (mouse movement, typing, etc.).

4. **Timing considerations**

   * Send updates at appropriate moments.
   * Consider grouping multiple contextual updates into a single update (instead of sending every small change separately).
   * Balance between keeping the session alive and avoiding excessive messaging.

<Info>
  For detailed implementation examples, check our [SDK
  documentation](/docs/agents-platform/libraries/python).
</Info>


# Integrate your own model

> Connect an agent to your own LLM or host your own server.

<Note>
  Custom LLM allows you to connect your conversations to your own LLM via an external endpoint.
  ElevenLabs also supports [natively integrated LLMs](/docs/agents-platform/customization/llm)
</Note>

**Custom LLMs** let you bring your own OpenAI API key or run an entirely custom LLM server.

## Overview

By default, we use our own internal credentials for popular models like OpenAI. To use a custom LLM server, it must align with the OpenAI [create chat completion](https://platform.openai.com/docs/api-reference/chat/create) request/response structure.

The following guides cover both use cases:

1. **Bring your own OpenAI key**: Use your own OpenAI API key with our platform.
2. **Custom LLM server**: Host and connect your own LLM server implementation.

You'll learn how to:

* Store your OpenAI API key in ElevenLabs
* host a server that replicates OpenAI's [create chat completion](https://platform.openai.com/docs/api-reference/chat/create) endpoint
* Direct ElevenLabs to your custom endpoint
* Pass extra parameters to your LLM as needed

<br />

## Using your own OpenAI key

To integrate a custom OpenAI key, create a secret containing your OPENAI\_API\_KEY:

<Steps>
  <Step>
    Navigate to the "Secrets" page and select "Add Secret"

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4b886cb2e6c49585bf0512aef1a4611041984e6760f794a1938c0db623ffc0f9/assets/images/conversational-ai/byollm-1.png)
    </Frame>
  </Step>

  <Step>
    Choose "Custom LLM" from the dropdown menu.

    <Frame background="subtle">
      ![Choose custom llm](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/45ec75f558a5c8e5070bd3170d96cbc54ef63e15d9f04ac472a45854a22a17ac/assets/images/conversational-ai/byollm-2.png)
    </Frame>
  </Step>

  <Step>
    Enter the URL, your model, and the secret you created.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1f519bdd2dff09797d00c893f4c40cfb525809a751b7c5381121b019a587c42e/assets/images/conversational-ai/byollm-3.png)
    </Frame>
  </Step>

  <Step>
    Set "Custom LLM extra body" to true.

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/55beb285e9c446ef2e2a137c9260eda55c55c0ef6c8bee0198f82c0931e3642f/assets/images/conversational-ai/byollm-4.png)
    </Frame>
  </Step>
</Steps>

## Custom LLM Server

To bring a custom LLM server, set up a compatible server endpoint using OpenAI's style, specifically targeting create\_chat\_completion.

Here's an example server implementation using FastAPI and OpenAI's Python SDK:

```python
import json
import os
import fastapi
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI
import uvicorn
import logging
from dotenv import load_dotenv
from pydantic import BaseModel
from typing import List, Optional

# Load environment variables from .env file
load_dotenv()

# Retrieve API key from environment
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY not found in environment variables")

app = fastapi.FastAPI()
oai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)

class Message(BaseModel):
    role: str
    content: str

class ChatCompletionRequest(BaseModel):
    messages: List[Message]
    model: str
    temperature: Optional[float] = 0.7
    max_tokens: Optional[int] = None
    stream: Optional[bool] = False
    user_id: Optional[str] = None

@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
    oai_request = request.dict(exclude_none=True)
    if "user_id" in oai_request:
        oai_request["user"] = oai_request.pop("user_id")

    chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)

    async def event_stream():
        try:
            async for chunk in chat_completion_coroutine:
                # Convert the ChatCompletionChunk to a dictionary before JSON serialization
                chunk_dict = chunk.model_dump()
                yield f"data: {json.dumps(chunk_dict)}\n\n"
            yield "data: [DONE]\n\n"
        except Exception as e:
            logging.error("An error occurred: %s", str(e))
            yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"

    return StreamingResponse(event_stream(), media_type="text/event-stream")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8013)
```

Run this code or your own server code.

<Frame background="subtle">
  ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8032697eeac9a62bb084feb13ab05294df2fee44f14a97897f0b7c10ffee813c/assets/images/conversational-ai/byollm-5.png)
</Frame>

### Setting Up a Public URL for Your Server

To make your server accessible, create a public URL using a tunneling tool like ngrok:

```shell
ngrok http --url=<Your url>.ngrok.app 8013
```

<Frame background="subtle">
  ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/16d139cc2889d46e026c8aa7578fcdcd8d228dbe0f4df245091ea6de2ceb345a/assets/images/conversational-ai/byollm-6.png)
</Frame>

### Configuring Elevenlabs CustomLLM

Now let's make the changes in Elevenlabs

<Frame background="subtle">
  ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/b2fbcd2f14c477820bb0c8b4a75823041cdab84fa1a6c1abad61ba59fc9b123e/assets/images/conversational-ai/byollm-8.png)
</Frame>

<Frame background="subtle">
  ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/281a99a47b35c59fd264ae7515f2cbc312577ed4079726947ede8ca218fd8f0d/assets/images/conversational-ai/byollm-7.png)
</Frame>

Direct your server URL to ngrok endpoint, setup "Limit token usage" to 5000 and set "Custom LLM extra body" to true.

You can start interacting with ElevenAgents with your own LLM server

## Optimizing for slow processing LLMs

If your custom LLM has slow processing times (perhaps due to agentic reasoning or pre-processing requirements) you can improve the conversational flow by implementing **buffer words** in your streaming responses. This technique helps maintain natural speech prosody while your LLM generates the complete response.

### Buffer words

When your LLM needs more time to process the full response, return an initial response ending with `"... "` (ellipsis followed by a space). This allows the Text to Speech system to maintain natural flow while keeping the conversation feeling dynamic.
This creates natural pauses that flow well into subsequent content that the LLM can reason longer about. The extra space is crucial to ensure that the subsequent content is not appended to the "..." which can lead to audio distortions.

### Implementation

Here's how to modify your custom LLM server to implement buffer words:

<CodeBlocks>
  ```python title="server.py"
  @app.post("/v1/chat/completions")
  async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
      oai_request = request.dict(exclude_none=True)
      if "user_id" in oai_request:
          oai_request["user"] = oai_request.pop("user_id")

      async def event_stream():
          try:
              # Send initial buffer chunk while processing
              initial_chunk = {
                  "id": "chatcmpl-buffer",
                  "object": "chat.completion.chunk",
                  "created": 1234567890,
                  "model": request.model,
                  "choices": [{
                      "delta": {"content": "Let me think about that... "},
                      "index": 0,
                      "finish_reason": None
                  }]
              }
              yield f"data: {json.dumps(initial_chunk)}\n\n"

              # Process the actual LLM response
              chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)

              async for chunk in chat_completion_coroutine:
                  chunk_dict = chunk.model_dump()
                  yield f"data: {json.dumps(chunk_dict)}\n\n"
              yield "data: [DONE]\n\n"

          except Exception as e:
              logging.error("An error occurred: %s", str(e))
              yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"

      return StreamingResponse(event_stream(), media_type="text/event-stream")

  ```

  ```typescript title="server.ts"
  app.post('/v1/chat/completions', async (req: Request, res: Response) => {
    const request = req.body as ChatCompletionRequest;
    const oaiRequest = { ...request };

    if (oaiRequest.user_id) {
      oaiRequest.user = oaiRequest.user_id;
      delete oaiRequest.user_id;
    }

    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    try {
      // Send initial buffer chunk while processing
      const initialChunk = {
        id: "chatcmpl-buffer",
        object: "chat.completion.chunk",
        created: Math.floor(Date.now() / 1000),
        model: request.model,
        choices: [{
          delta: { content: "Let me think about that... " },
          index: 0,
          finish_reason: null
        }]
      };
      res.write(`data: ${JSON.stringify(initialChunk)}\n\n`);

      // Process the actual LLM response
      const stream = await openai.chat.completions.create({
        ...oaiRequest,
        stream: true
      });

      for await (const chunk of stream) {
        res.write(`data: ${JSON.stringify(chunk)}\n\n`);
      }

      res.write('data: [DONE]\n\n');
      res.end();

    } catch (error) {
      console.error('An error occurred:', error);
      res.write(`data: ${JSON.stringify({ error: 'Internal error occurred!' })}\n\n`);
      res.end();
    }
  });
  ```
</CodeBlocks>

## System tools integration

Your custom LLM can trigger [system tools](/docs/agents-platform/customization/tools/system-tools) to control conversation flow and state. These tools are automatically included in the `tools` parameter of your chat completion requests when configured in your agent.

### How system tools work

1. **LLM Decision**: Your custom LLM decides when to call these tools based on conversation context
2. **Tool Response**: The LLM responds with function calls in standard OpenAI format
3. **Backend Processing**: ElevenLabs processes the tool calls and updates conversation state

For more information on system tools, please see [our guide](/docs/agents-platform/customization/tools/system-tools)

### Available system tools

<AccordionGroup>
  <Accordion title="End call">
    **Purpose**: Automatically terminate conversations when appropriate conditions are met.

    **Trigger conditions**: The LLM should call this tool when:

    * The main task has been completed and user is satisfied
    * The conversation reached natural conclusion with mutual agreement
    * The user explicitly indicates they want to end the conversation

    **Parameters**:

    * `reason` (string, required): The reason for ending the call
    * `message` (string, optional): A farewell message to send to the user before ending the call

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "end_call",
        "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
      }
    }
    ```

    **Implementation**: Configure as a system tool in your agent settings. The LLM will receive detailed instructions about when to call this function.

    Learn more: [End call tool](/docs/agents-platform/customization/tools/system-tools/end-call)
  </Accordion>

  <Accordion title="Language detection">
    **Purpose**: Automatically switch to the user's detected language during conversations.

    **Trigger conditions**: The LLM should call this tool when:

    * User speaks in a different language than the current conversation language
    * User explicitly requests to switch languages
    * Multi-language support is needed for the conversation

    **Parameters**:

    * `reason` (string, required): The reason for the language switch
    * `language` (string, required): The language code to switch to (must be in supported languages list)

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "language_detection",
        "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
      }
    }
    ```

    **Implementation**: Configure supported languages in agent settings and add the language detection system tool. The agent will automatically switch voice and responses to match detected languages.

    Learn more: [Language detection tool](/docs/agents-platform/customization/tools/system-tools/language-detection)
  </Accordion>

  <Accordion title="Agent transfer">
    **Purpose**: Transfer conversations between specialized AI agents based on user needs.

    **Trigger conditions**: The LLM should call this tool when:

    * User request requires specialized knowledge or different agent capabilities
    * Current agent cannot adequately handle the query
    * Conversation flow indicates need for different agent type

    **Parameters**:

    * `reason` (string, optional): The reason for the agent transfer
    * `agent_number` (integer, required): Zero-indexed number of the agent to transfer to (based on configured transfer rules)

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "transfer_to_agent",
        "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
      }
    }
    ```

    **Implementation**: Define transfer rules mapping conditions to specific agent IDs. Configure which agents the current agent can transfer to. Agents are referenced by zero-indexed numbers in the transfer configuration.

    Learn more: [Agent transfer tool](/docs/agents-platform/customization/tools/system-tools/agent-transfer)
  </Accordion>

  <Accordion title="Transfer to human">
    **Purpose**: Seamlessly hand off conversations to human operators when AI assistance is insufficient.

    **Trigger conditions**: The LLM should call this tool when:

    * Complex issues requiring human judgment
    * User explicitly requests human assistance
    * AI reaches limits of capability for the specific request
    * Escalation protocols are triggered

    **Parameters**:

    * `reason` (string, optional): The reason for the transfer
    * `transfer_number` (string, required): The phone number to transfer to (must match configured numbers)
    * `client_message` (string, required): Message read to the client while waiting for transfer
    * `agent_message` (string, required): Message for the human operator receiving the call

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "transfer_to_number",
        "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
      }
    }
    ```

    **Implementation**: Configure transfer phone numbers and conditions. Define messages for both customer and receiving human operator. Works with both Twilio and SIP trunking.

    Learn more: [Transfer to human tool](/docs/agents-platform/customization/tools/system-tools/transfer-to-human)
  </Accordion>

  <Accordion title="Skip turn">
    **Purpose**: Allow the agent to pause and wait for user input without speaking.

    **Trigger conditions**: The LLM should call this tool when:

    * User indicates they need a moment ("Give me a second", "Let me think")
    * User requests pause in conversation flow
    * Agent detects user needs time to process information

    **Parameters**:

    * `reason` (string, optional): Free-form reason explaining why the pause is needed

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "skip_turn",
        "arguments": "{\"reason\": \"User requested time to think\"}"
      }
    }
    ```

    **Implementation**: No additional configuration needed. The tool simply signals the agent to remain silent until the user speaks again.

    Learn more: [Skip turn tool](/docs/agents-platform/customization/tools/system-tools/skip-turn)
  </Accordion>

  <Accordion title="Voicemail detection">
    **Parameters**:

    * `reason` (string, required): The reason for detecting voicemail (e.g., "automated greeting detected", "no human response")

    **Function call format**:

    ```json
    {
      "type": "function",
      "function": {
        "name": "voicemail_detection",
        "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
      }
    }
    ```

    Learn more: [Voicemail detection tool](/docs/agents-platform/customization/tools/system-tools/voicemail-detection)
  </Accordion>
</AccordionGroup>

### Example Request with System Tools

When system tools are configured, your custom LLM will receive requests that include the tools in the standard OpenAI format:

```json
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. You have access to system tools for managing conversations."
    },
    {
      "role": "user",
      "content": "I think we're done here, thanks for your help!"
    }
  ],
  "model": "your-custom-model",
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": true,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "end_call",
        "description": "Call this function to end the current conversation when the main task has been completed...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "The reason for the tool call."
            },
            "message": {
              "type": "string",
              "description": "A farewell message to send to the user along right before ending the call."
            }
          },
          "required": ["reason"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "language_detection",
        "description": "Change the conversation language when the user expresses a language preference explicitly...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "The reason for the tool call."
            },
            "language": {
              "type": "string",
              "description": "The language to switch to. Must be one of language codes in tool description."
            }
          },
          "required": ["reason", "language"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "skip_turn",
        "description": "Skip a turn when the user explicitly indicates they need a moment to think...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Optional free-form reason explaining why the pause is needed."
            }
          },
          "required": []
        }
      }
    }
  ]
}
```

<Note>
  Your custom LLM must support function calling to use system tools. Ensure your model can generate
  proper function call responses in OpenAI format.
</Note>

# Additional Features

<Accordion title="Custom LLM Parameters">
  You may pass additional parameters to your custom LLM implementation.

  <Tabs>
    <Tab title="Python">
      <Steps>
        <Step title="Define the Extra Parameters">
          Create an object containing your custom parameters:

          ```python
          from elevenlabs.conversational_ai.conversation import Conversation, ConversationConfig

          extra_body_for_convai = {
              "UUID": "123e4567-e89b-12d3-a456-426614174000",
              "parameter-1": "value-1",
              "parameter-2": "value-2",
          }

          config = ConversationConfig(
              extra_body=extra_body_for_convai,
          )
          ```
        </Step>

        <Step title="Update the LLM Implementation">
          Modify your custom LLM code to handle the additional parameters:

          ```python
          import json
          import os
          import fastapi
          from fastapi.responses import StreamingResponse
          from fastapi import Request
          from openai import AsyncOpenAI
          import uvicorn
          import logging
          from dotenv import load_dotenv
          from pydantic import BaseModel
          from typing import List, Optional

          # Load environment variables from .env file
          load_dotenv()

          # Retrieve API key from environment
          OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
          if not OPENAI_API_KEY:
              raise ValueError("OPENAI_API_KEY not found in environment variables")

          app = fastapi.FastAPI()
          oai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)

          class Message(BaseModel):
              role: str
              content: str

          class ChatCompletionRequest(BaseModel):
              messages: List[Message]
              model: str
              temperature: Optional[float] = 0.7
              max_tokens: Optional[int] = None
              stream: Optional[bool] = False
              user_id: Optional[str] = None
              elevenlabs_extra_body: Optional[dict] = None

          @app.post("/v1/chat/completions")
          async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
              oai_request = request.dict(exclude_none=True)
              print(oai_request)
              if "user_id" in oai_request:
                  oai_request["user"] = oai_request.pop("user_id")

              if "elevenlabs_extra_body" in oai_request:
                  oai_request.pop("elevenlabs_extra_body")

              chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)

              async def event_stream():
                  try:
                      async for chunk in chat_completion_coroutine:
                          chunk_dict = chunk.model_dump()
                          yield f"data: {json.dumps(chunk_dict)}\n\n"
                      yield "data: [DONE]\n\n"
                  except Exception as e:
                      logging.error("An error occurred: %s", str(e))
                      yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"

              return StreamingResponse(event_stream(), media_type="text/event-stream")

          if __name__ == "__main__":
              uvicorn.run(app, host="0.0.0.0", port=8013)
          ```
        </Step>
      </Steps>

      ### Example Request

      With this custom message setup, your LLM will receive requests in this format:

      ```json
      {
        "messages": [
          {
            "role": "system",
            "content": "\n  <Redacted>"
          },
          {
            "role": "assistant",
            "content": "Hey I'm currently unavailable."
          },
          {
            "role": "user",
            "content": "Hey, who are you?"
          }
        ],
        "model": "gpt-4o",
        "temperature": 0.5,
        "max_tokens": 5000,
        "stream": true,
        "elevenlabs_extra_body": {
          "UUID": "123e4567-e89b-12d3-a456-426614174000",
          "parameter-1": "value-1",
          "parameter-2": "value-2"
        }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>


# Cloudflare Workers AI

> Connect an agent to a custom LLM on Cloudflare Workers AI.

## Overview

[Cloudflare's Workers AI platform](https://developers.cloudflare.com/workers-ai/) lets you run machine learning models, powered by serverless GPUs, on Cloudflare's global network, even on the free plan!

Workers AI comes with a curated set of [popular open-source models](https://developers.cloudflare.com/workers-ai/models/) that enable you to do tasks such as image classification, text generation, object detection and more.

## Choosing a model

To make use of the full power of ElevenLabs Agents you need to use a model that supports [function calling](https://developers.cloudflare.com/workers-ai/function-calling/#what-models-support-function-calling).

When browsing the [model catalog](https://developers.cloudflare.com/workers-ai/models/), look for models with the function calling property beside it.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/8iwPIdzTwAA?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Tip title="Try out DeepSeek R1" icon="leaf">
  Cloudflare Workers AI provides access to
  [DeepSeek-R1-Distill-Qwen-32B](https://developers.cloudflare.com/workers-ai/models/deepseek-r1-distill-qwen-32b/),
  a model distilled from DeepSeek-R1 based on Qwen2.5. It outperforms OpenAI-o1-mini across various
  benchmarks, achieving new state-of-the-art results for dense models.
</Tip>

## Set up DeepSeek R1 on Cloudflare Workers AI

<Steps>
  <Step>
    Navigate to [dash.cloudflare.com](https://dash.cloudflare.com) and create or sign in to your account. In the navigation, select AI > Workers AI, and then click on the "Use REST API" widget.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ba8414d3dc5f806d004f8b4ac0c7dc0d77a0b292a9dbd86dfb8b2d6736a40118/assets/images/conversational-ai/cloudflare-workers-ai/cloudflare-workers-ai-api-key.png)
    </Frame>
  </Step>

  <Step>
    Once you have your API key, you can try it out immediately with a curl request. Cloudflare provides an OpenAI-compatible API endpoint making this very convenient. At this point make a note of the model and the full endpoint — including the account ID. For example: `https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}c/ai/v1/`.

    ```bash
    curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1/chat/completions \
    -X POST \
    -H "Authorization: Bearer {API_TOKEN}" \
    -d '{
        "model": "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "How many Rs in the word Strawberry?"}
        ],
        "stream": false
      }'
    ```
  </Step>

  <Step>
    Navigate to your [AI Agent](https://elevenlabs.io/app/agents), scroll down to the "Secrets" section and select "Add Secret". After adding the secret, make sure to hit "Save" to make the secret available to your agent.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/59dbfcd46a69b9f28e58e68de7b3dd678ee9f6bfd499fd23699017e92b11931f/assets/images/conversational-ai/cloudflare-workers-ai/cloudflare-workers-ai-secret.png)
    </Frame>
  </Step>

  <Step>
    Choose "Custom LLM" from the dropdown menu.

    <Frame background="subtle">
      ![Choose custom llm](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/45ec75f558a5c8e5070bd3170d96cbc54ef63e15d9f04ac472a45854a22a17ac/assets/images/conversational-ai/byollm-2.png)
    </Frame>
  </Step>

  <Step>
    For the Server URL, specify Cloudflare's OpenAI-compatible API endpoint: `https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1/`. For the Model ID, specify `@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` as discussed above, and select your API key from the dropdown menu.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/da17a1626b64d7b3eadb23ee17eb0e7bd3bb5156f8edf2357816820169d74d94/assets/images/conversational-ai/cloudflare-workers-ai/cloudflare-workers-ai-llm.png)
    </Frame>
  </Step>

  <Step>
    Now you can go ahead and click "Test AI Agent" to chat with your custom DeepSeek R1 model.
  </Step>
</Steps>


# Groq Cloud

> Connect an agent to a custom LLM on Groq Cloud.

## Overview

[Groq Cloud](https://console.groq.com/) provides easy access to fast AI inference, giving you OpenAI-compatible API endpoints in a matter of clicks.

Use leading [Openly-available Models](https://console.groq.com/docs/overview/models) like Llama, Mixtral, and Gemma as the brain for your ElevenLabs agents in a few easy steps.

## Choosing a model

To make use of the full power of ElevenLabs agents you need to use a model that supports tool use and structured outputs. Groq recommends the following Llama-3.3 models their versatility and performance:

* meta-llama/llama-4-scout-17b-16e-instruct (10M token context window) and support for 12 languages (Arabic, English, French, German, Hindi, Indonesian, Italian, Portuguese, Spanish, Tagalog, Thai, and Vietnamese)
* llama-3.3-70b-versatile (128k context window | 32,768 max output tokens)
* llama-3.1-8b-instant (128k context window | 8,192 max output tokens)

With this in mind, it's recommended to use `meta-llama/llama-4-scout-17b-16e-instruct` for your ElevenLabs Agents agent.

## Set up Llama 3.3 on Groq Cloud

<Steps>
  <Step>
    Navigate to [console.groq.com/keys](https://console.groq.com/keys) and create a new API key.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2dc1bdac30871fb4059a394b8edfedd4cf953f8e1f787ca8b807a9f195e7fdf3/assets/images/conversational-ai/groq-cloud/groq-api-key.png)
    </Frame>
  </Step>

  <Step>
    Once you have your API key, you can test it by running the following curl command:

    ```bash
    curl https://api.groq.com/openai/v1/chat/completions -s \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $GROQ_API_KEY" \
    -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{
        "role": "user",
        "content": "Hello, how are you?"
    }]
    }'
    ```
  </Step>

  <Step>
    Navigate to your [AI Agent](https://elevenlabs.io/app/agents), scroll down to the "Secrets" section and select "Add Secret". After adding the secret, make sure to hit "Save" to make the secret available to your agent.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/464e123d926fbd9e6986a382af8da55d9f3861d1e593bb1f4b41ba33bed67ae1/assets/images/conversational-ai/groq-cloud/groq-secret.png)
    </Frame>
  </Step>

  <Step>
    Choose "Custom LLM" from the dropdown menu.

    <Frame background="subtle">
      ![Choose custom llm](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/45ec75f558a5c8e5070bd3170d96cbc54ef63e15d9f04ac472a45854a22a17ac/assets/images/conversational-ai/byollm-2.png)
    </Frame>
  </Step>

  <Step>
    For the Server URL, specify Groq's OpenAI-compatible API endpoint: `https://api.groq.com/openai/v1`. For the Model ID, specify `meta-llama/llama-4-scout-17b-16e-instruct` as discussed above, and select your API key from the dropdown menu.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/70555982e71101023f8e988102ab505c964fd6796a190a9bce74f3c0ed1b56be/assets/images/conversational-ai/groq-cloud/groq-llm.png)
    </Frame>
  </Step>

  <Step>
    Now you can go ahead and click "Test AI Agent" to chat with your custom Llama 3.3 model.
  </Step>
</Steps>


# SambaNova Cloud

> Connect an agent to a custom LLM on SambaNova Cloud.

## Overview

[SambaNova Cloud](http://cloud.sambanova.ai?utm_source=elevenlabs\&utm_medium=external\&utm_campaign=cloud_signup) is the fastest provider of the best [open source models](https://docs.sambanova.ai/cloud/docs/get-started/supported-models), including DeepSeek R1, DeepSeek V3, Llama 4 Maverick and others. Through an
OpenAI-compatible API endpoint, you can set up your ElevenLabs agent on ElevenLabs in a just few minutes.

Watch this [video](https://www.youtube.com/watch?v=46W96JcE_p8) for a walkthrough and demo of how you can configure your ElevenLabs Agents agent to leverage SambaNova's blazing-fast LLMs!

## Choosing a model

To make use of the full power of ElevenLabs Agents you need to use a model that supports tool use and structured outputs. SambaNova recommends the following models for their accuracy and performance:

* `DeepSeek-V3-0324` (671B model)
* `Meta-Llama-3.3-70B-Instruct`
* `Llama-4-Maverick-17B-128E-Instruct`
* `Qwen3-32B`

For up-to-date information on model-specific context windows, please refer to [this](https://docs.sambanova.ai/cloud/docs/get-started/supported-models) page.

Note that `Meta-Llama-3.3-70B-Instruct` is SambaNova's most battle-tested model. If any model is causing issues, you may report it on SambaNova's [Community page](https://community.sambanova.ai).

## Configuring your ElevenLabs agent with a SambaNova LLM

<Steps>
  <Step>
    Navigate to [cloud.sambanova.ai/apis](https://cloud.sambanova.ai/apis?utm_source=elevenlabs\&utm_medium=external\&utm_campaign=cloud_signup) and create a new API key.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/9f15e96bc7394d1be5936a155aeaf3c450c48b1164623c0ca3a05f723aec81cd/assets/images/conversational-ai/sambanova-cloud/sn-api-key.png)
    </Frame>
  </Step>

  <Step>
    Once you have your API key, you can test it by running the following curl command:

    ```bash
    curl -H "Authorization: Bearer <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
    "stream": true,
    "model": "DeepSeek-V3-0324",
    "messages": [
    	{
    		"role": "system",
    		"content": "You are a helpful assistant"
    	},
    	{
    		"role": "user",
    		"content": "Hello"
    	}
    ]
    }' \
     -X POST https://api.sambanova.ai/v1/chat/completions
    ```
  </Step>

  <Step>
    Create a new [AI Agent](https://elevenlabs.io/app/agents/agents) or edit an existing one.
  </Step>

  <Step>
    Scroll down to the "Workspace Secrets" section and select "Add Secret". Name the key `SAMBANOVA_API_KEY` and copy the value from the SambaNova Cloud dashboard. Be sure to hit "Save" to make the secret available to your agent.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8505deccfb198fbf8d33e3b936f65bf85caf59811bffbb708a5d526faa3329bc/assets/images/conversational-ai/sambanova-cloud/workspace-secret.png)
    </Frame>
  </Step>

  <Step>
    Choose "Custom LLM" from the dropdown menu.

    <Frame background="subtle">
      ![Choose custom llm](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/45ec75f558a5c8e5070bd3170d96cbc54ef63e15d9f04ac472a45854a22a17ac/assets/images/conversational-ai/byollm-2.png)
    </Frame>
  </Step>

  <Step>
    For the Server URL, specify SambaNova's OpenAI-compatible API endpoint: `https://api.sambanova.ai/v1`. For the Model ID, specify one the model names indicated above (e.g., `Meta-Llama-3.3-70B-Instruct`) and select the `SAMBANOVA_API_KEY` API key from the dropdown menu.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d1e6fec480a23a0c3b11ca3b675dfddeaffe59f7a24becfaf1986675b109b99b/assets/images/conversational-ai/sambanova-cloud/sn-llm.png)
    </Frame>
  </Step>

  <Step>
    Set the max tokens to 1024 to restrict the agent's output for brevity. Also be sure to include an instruction in the System Prompt for the model to respond in 500 words or less.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/2be33272ea2e7aaf6166d482a41bdf492f3a75f1e43e2e8cb9cf363fb3b6188f/assets/images/conversational-ai/sambanova-cloud/sn-maxtokens.png)
    </Frame>
  </Step>

  <Step>
    Save your changes and click on "Test AI Agent" to chat with your SambaNova-powered agent!
  </Step>
</Steps>


# Together AI

> Connect an agent to a custom LLM on Together AI.

## Overview

[Together AI](https://www.together.ai/) provides an AI Acceleration Cloud, allowing you to train, fine-tune, and run inference on AI models blazing fast, at low cost, and at production scale.

Instantly run [200+ models](https://together.xyz/models) including DeepSeek, Llama3, Mixtral, and Stable Diffusion, optimized for peak latency, throughput, and context length.

## Choosing a model

To make use of the full power of ElevenLabs Agents you need to use a model that supports tool use and structured outputs. Together AI supports function calling for [these models](https://docs.together.ai/docs/function-calling):

* meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
* meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo
* meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo
* meta-llama/Llama-3.3-70B-Instruct-Turbo
* mistralai/Mixtral-8x7B-Instruct-v0.1
* mistralai/Mistral-7B-Instruct-v0.1

With this in mind, it's recommended to use at least `meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` for your ElevenLabs Agents agent.

## Set up Llama 3.1 on Together AI

<Steps>
  <Step>
    Navigate to [api.together.xyz/settings/api-keys](https://api.together.xyz/settings/api-keys) and create a new API key.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/97323ef6ffb761b54a7b5c4183054bc1fd621d1069a38cbeb474444e84de75f4/assets/images/conversational-ai/together-ai/together-ai-api-key.png)
    </Frame>
  </Step>

  <Step>
    Once you have your API key, you can test it by running the following curl command:

    ```bash
    curl https://api.together.xyz/v1/chat/completions -s \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>" \
    -d '{
    "model": "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
    "messages": [{
        "role": "user",
        "content": "Hello, how are you?"
    }]
    }'
    ```
  </Step>

  <Step>
    Navigate to your [AI Agent](https://elevenlabs.io/app/agents), scroll down to the "Secrets" section and select "Add Secret". After adding the secret, make sure to hit "Save" to make the secret available to your agent.

    <Frame background="subtle">
      ![Add Secret](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/43e5478a3c62f31d2d9f66f9919e7c4c1b5878e3b79681d08741221ce3e689d8/assets/images/conversational-ai/together-ai/together-ai-secret.png)
    </Frame>
  </Step>

  <Step>
    Choose "Custom LLM" from the dropdown menu.

    <Frame background="subtle">
      ![Choose custom llm](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/45ec75f558a5c8e5070bd3170d96cbc54ef63e15d9f04ac472a45854a22a17ac/assets/images/conversational-ai/byollm-2.png)
    </Frame>
  </Step>

  <Step>
    For the Server URL, specify Together AI's OpenAI-compatible API endpoint: `https://api.together.xyz/v1`. For the Model ID, specify `meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` as discussed above, and select your API key from the dropdown menu.

    <Frame background="subtle">
      ![Enter url](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/94d7f96a16d483327751195b306431b5d7c0e4df237510b74d7e98f28b58efe1/assets/images/conversational-ai/together-ai/together-ai-llm.png)
    </Frame>
  </Step>

  <Step>
    Now you can go ahead and click "Test AI Agent" to chat with your custom Llama 3.1 model.
  </Step>
</Steps>


# LLM Cascading

> Learn how Agents Platform ensures reliable LLM responses using a cascading fallback mechanism.

## Overview

Agents Platform employs an LLM cascading mechanism to enhance the reliability and resilience of its text generation capabilities. This system automatically attempts to use backup Large Language Models (LLMs) if the primary configured LLM fails, ensuring a smoother and more consistent user experience.

Failures can include API errors, timeouts, or empty responses from the LLM provider. The cascade logic handles these situations gracefully.

## How it Works

The cascading process follows a defined sequence:

1. **Preferred LLM Attempt:** The system first attempts to generate a response using the LLM selected in the agent's configuration.

2. **Backup LLM Sequence:** If the preferred LLM fails, the system automatically falls back to a predefined sequence of backup LLMs. This sequence is curated based on model performance, speed, and reliability. The current default sequence (subject to change) is:

   1. Gemini 2.5 Flash
   2. Gemini 2.0 Flash
   3. Gemini 2.0 Flash Lite
   4. Claude 3.7 Sonnet
   5. Claude 3.5 Sonnet v2
   6. Claude 3.5 Sonnet v1
   7. GPT-4o
   8. Gemini 1.5 Pro
   9. Gemini 1.5 Flash

3. **HIPAA Compliance:** If the agent operates in a mode requiring strict data privacy (HIPAA compliance / zero data retention), the backup list is filtered to include only compliant models from the sequence above.

4. **Retries:** The system retries the generation process multiple times (at least 3 attempts) across the sequence of available LLMs (preferred + backups). If a backup LLM also fails, it proceeds to the next one in the sequence. If it runs out of unique backup LLMs within the retry limit, it may retry previously failed backup models.

5. **Lazy Initialization:** Backup LLM connections are initialized only when needed, optimizing resource usage.

<Info>
  The specific list and order of backup LLMs are managed internally by ElevenLabs and optimized for
  performance and availability. The sequence listed above represents the current default but may be
  updated without notice.
</Info>

## Custom LLMs

When you configure a [Custom LLM](/docs/agents-platform/customization/llm/custom-llm), the standard cascading logic to *other* models is bypassed. The system will attempt to use your specified Custom LLM.

If your Custom LLM fails, the system will retry the request with the *same* Custom LLM multiple times (matching the standard minimum retry count) before considering the request failed. It will not fall back to ElevenLabs-hosted models, ensuring your specific configuration is respected.

## Benefits

* **Increased Reliability:** Reduces the impact of temporary issues with a specific LLM provider.
* **Higher Availability:** Increases the likelihood of successfully generating a response even during partial LLM outages.
* **Seamless Operation:** The fallback mechanism is automatic and transparent to the end-user.

## Configuration

LLM cascading is an automatic background process. The only configuration required is selecting your **Preferred LLM** in the agent's settings. The system handles the rest to ensure robust performance.


# Post-call webhooks

> Get notified when calls end and analysis is complete through webhooks.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/rqxEz18SS_k?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

Post-call [Webhooks](/docs/overview/administration/webhooks) allow you to receive detailed information about a call after analysis is complete. When enabled, ElevenLabs will send a POST request to your specified endpoint with comprehensive call data.

ElevenLabs supports three types of post-call webhooks:

* **Transcription webhooks** (`post_call_transcription`): Contains full conversation data including transcripts, analysis results, and metadata
* **Audio webhooks** (`post_call_audio`): Contains minimal data with base64-encoded audio of the full conversation
* **Call initiation failure webhooks** (`call_initiation_failure`): Contains information about failed call initiation attempts including failure reasons and metadata

## Migration Notice: Enhanced Webhook Format

<Warning>
  **Important:** Post-call transcription webhooks will be migrated to include additional fields for
  enhanced compatibility and consistency, ensure your endpoint can handle the extra fields.
</Warning>

### What's Changing

Post-call transcription webhooks will be updated to match the same format as the [GET Conversation response](/docs/api-reference/conversations/get). The webhook `data` object will include three additional boolean fields:

* `has_audio`: Boolean indicating whether the conversation has any audio available
* `has_user_audio`: Boolean indicating whether user audio is available for the conversation
* `has_response_audio`: Boolean indicating whether agent response audio is available for the conversation

### Migration Requirements

To ensure your webhook handlers continue working after the migration:

1. **Update your webhook parsing logic** to handle these three new boolean fields
2. **Test your webhook endpoints** with the new field structure before August 15th, 2025
3. **Ensure your JSON parsing** can gracefully handle additional fields without breaking

### Benefits After Migration

Once the migration is complete:

* **Unified data model**: Webhook responses will match the GET Conversation API format exactly
* **SDK compatibility**: Webhook handlers can be provided in the SDK and automatically stay up-to-date with the GET response model

## Enabling post-call webhooks

Post-call webhooks can be enabled for all agents in your workspace through the ElevenAgents [settings page](https://elevenlabs.io/app/agents/settings).

<Frame background="subtle">
  ![Post-call webhook settings](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f5edf1792c3791281ade98202614e51d7e93b7b3f6e25db1fdb261d71c13b5ef/assets/images/conversational-ai/postcallwebhooksettings.png)
</Frame>

<Warning>
  Post call webhooks must return a 200 status code to be considered successful. Webhooks that
  repeatedly fail are auto disabled if there are 10 or more consecutive failures and the last
  successful delivery was more than 7 days ago or has never been successfully delivered.
</Warning>

<Note>
  For HIPAA compliance, if a webhook fails we can not retry the webhook.
</Note>

### Authentication

It is important for the listener to validate all incoming webhooks. Webhooks currently support authentication via HMAC signatures. Set up HMAC authentication by:

* Securely storing the shared secret generated upon creation of the webhook
* Verifying the ElevenLabs-Signature header in your endpoint using the SDK

The ElevenLabs SDK provides a `constructEvent` method that handles signature verification, timestamp validation, and payload parsing.

<Tabs>
  <Tab title="Python">
    Example webhook handler using FastAPI:

    ```python
    from dotenv import load_dotenv
    from fastapi import FastAPI, Request
    from fastapi.responses import JSONResponse
    from elevenlabs.client import ElevenLabs
    import os

    load_dotenv()

    app = FastAPI()
    elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
    )

    WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")

    @app.post("/webhook")
    async def receive_message(request: Request):
        payload = await request.body()
        signature = request.headers.get("elevenlabs-signature")

        try:
            event = elevenlabs.webhooks.construct_event(
                payload=payload.decode("utf-8"),
                signature=signature,
                secret=WEBHOOK_SECRET,
            )
        except Exception as e:
            return JSONResponse(content={"error": "Invalid signature"}, status_code=401)

        # Process the webhook event
        if event.type == "post_call_transcription":
            print(f"Received transcription: {event.data}")

        return {"status": "received"}
    ```
  </Tab>

  <Tab title="JavaScript">
    <Tabs>
      <Tab title="Express">
        Example webhook handler using Express:

        ```javascript
        import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
        import express from 'express';

        const app = express();

        const elevenlabs = new ElevenLabsClient();
        const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

        // Use express.text() to preserve raw body for signature verification
        app.post('/webhook', express.text({ type: 'application/json' }), async (req, res) => {
          const signature = req.headers['elevenlabs-signature'];
          const payload = req.body; // Raw string body

          let event;
          try {
            event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
          } catch (error) {
            return res.status(401).json({ error: 'Invalid signature' });
          }

          // Process the webhook event
          if (event.type === 'post_call_transcription') {
            console.log('Received transcription:', event.data);
          }

          res.status(200).json({ received: true });
        });
        ```
      </Tab>

      <Tab title="Next.js">
        Example webhook handler using Next.js API route:

        ```typescript app/api/webhook/route.ts
        import { NextResponse } from 'next/server';
        import type { NextRequest } from 'next/server';
        import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

        const elevenlabs = new ElevenLabsClient();
        const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

        export async function POST(req: NextRequest) {
          const body = await req.text();
          const signature = req.headers.get('elevenlabs-signature');

          let event;
          try {
            event = await elevenlabs.webhooks.constructEvent(body, signature, WEBHOOK_SECRET);
          } catch (error) {
            return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
          }

          // Process the webhook event
          if (event.type === 'post_call_transcription') {
            console.log('Received transcription:', event.data);
          }

          return NextResponse.json({ received: true }, { status: 200 });
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### IP whitelisting

For additional security, you can whitelist the following static egress IPs from which ElevenLabs requests originate:

| Region       | IP Address     |
| ------------ | -------------- |
| US (Default) | 34.67.146.145  |
| US (Default) | 34.59.11.47    |
| EU           | 35.204.38.71   |
| EU           | 34.147.113.54  |
| Asia         | 35.185.187.110 |
| Asia         | 35.247.157.189 |

If you are using a [data residency region](/docs/overview/administration/data-residency) then the following IPs will be used:

| Region          | IP Address     |
| --------------- | -------------- |
| EU Residency    | 34.77.234.246  |
| EU Residency    | 34.140.184.144 |
| India Residency | 34.93.26.174   |
| India Residency | 34.93.252.69   |

If your infrastructure requires strict IP-based access controls, adding these IPs to your firewall allowlist will ensure you only receive requests from ElevenLabs' systems.

<Note>
  These static IPs are used across all ElevenLabs services including webhooks and MCP server
  requests, and will remain consistent.
</Note>

<Tip>
  Using IP whitelisting in combination with HMAC signature validation provides multiple layers of
  security.
</Tip>

## Webhook response structure

ElevenLabs sends three distinct types of post-call webhooks, each with different data structures:

### Transcription webhooks (`post_call_transcription`)

Contains comprehensive conversation data including full transcripts, analysis results, and metadata.

#### Top-level fields

| Field             | Type   | Description                                                            |
| ----------------- | ------ | ---------------------------------------------------------------------- |
| `type`            | string | Type of event (always `post_call_transcription`)                       |
| `data`            | object | Conversation data using the `ConversationHistoryCommonModel` structure |
| `event_timestamp` | number | When this event occurred in unix time UTC                              |

#### Data object structure

The `data` object contains:

| Field                                 | Type   | Description                                   |
| ------------------------------------- | ------ | --------------------------------------------- |
| `agent_id`                            | string | The ID of the agent that handled the call     |
| `conversation_id`                     | string | Unique identifier for the conversation        |
| `status`                              | string | Status of the conversation (e.g., "done")     |
| `user_id`                             | string | User identifier if available                  |
| `transcript`                          | array  | Complete conversation transcript with turns   |
| `metadata`                            | object | Call timing, costs, and phone details         |
| `analysis`                            | object | Evaluation results and conversation summary   |
| `conversation_initiation_client_data` | object | Configuration overrides and dynamic variables |

<Note>
  As of August 15th, 2025, transcription webhooks will include the `has_audio`, `has_user_audio`,
  and `has_response_audio` fields to match the [GET Conversation
  response](/docs/api-reference/conversations/get) format exactly. Prior to this date, these fields
  are not included in webhook payloads.
</Note>

### Audio webhooks (`post_call_audio`)

Contains minimal data with the full conversation audio as base64-encoded MP3.

#### Top-level fields

| Field             | Type   | Description                               |
| ----------------- | ------ | ----------------------------------------- |
| `type`            | string | Type of event (always `post_call_audio`)  |
| `data`            | object | Minimal audio data                        |
| `event_timestamp` | number | When this event occurred in unix time UTC |

#### Data object structure

The `data` object contains only:

| Field             | Type   | Description                                                                    |
| ----------------- | ------ | ------------------------------------------------------------------------------ |
| `agent_id`        | string | The ID of the agent that handled the call                                      |
| `conversation_id` | string | Unique identifier for the conversation                                         |
| `full_audio`      | string | Base64-encoded string containing the complete conversation audio in MP3 format |

<Warning>
  Audio webhooks contain only the three fields listed above. They do NOT include transcript data,
  metadata, analysis results, or any other conversation details.
</Warning>

### Call initiation failure webhooks (`call_initiation_failure`)

Contains information about telephony call initiation attempts, including failure reasons and telephony-provider metadata.

<Note>
  Call initiation failure webhook events are sent when a call fails to initiate due to connection
  errors, user declining the call, or user not picking up. If a call goes to voicemail or is picked
  up by an automated service, no call initiation failure webhook is sent as the call was
  successfully initiated.
</Note>

#### Top-level fields

| Field             | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| `type`            | string | Type of event (always `call_initiation_failure`) |
| `data`            | object | Call initiation failure data                     |
| `event_timestamp` | number | When this event occurred in unix time UTC        |

#### Data object structure

The `data` object contains:

| Field             | Type   | Description                                              |
| ----------------- | ------ | -------------------------------------------------------- |
| `agent_id`        | string | The ID of the agent that was assigned to handle the call |
| `conversation_id` | string | Unique identifier for the conversation                   |
| `failure_reason`  | string | The failure reason ("busy", "no-answer", "unknown")      |
| `metadata`        | object | Additional data provided by the telephony provider.      |

#### Metadata object structure

The `metadata` object structure varies depending on whether the outbound call was made via Twilio or via SIP trunking. The object includes a `type` field that distinguishes between the two, and a `body` field containing provider-specific details.

**SIP metadata** (`type: "sip"`):

| Field  | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `type` | string | Yes      | Provider type (always `sip`)          |
| `body` | object | Yes      | SIP-specific call failure information |

The `body` object for SIP metadata contains:

| Field             | Type   | Required | Description                                                                                      |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `from_number`     | number | Yes      | The phone number of the party that initiated the call.                                           |
| `to_number`       | number | Yes      | The phone number of the called party.                                                            |
| `sip_status_code` | number | Yes      | SIP response status code (e.g., 486 for busy)                                                    |
| `error_reason`    | string | Yes      | Human-readable error description                                                                 |
| `call_sid`        | string | Yes      | SIP call session identifier                                                                      |
| `twirp_code`      | string | No       | [Twirp error code](https://twitchtv.github.io/twirp/docs/spec_v7.html#error-codes) if applicable |
| `sip_status`      | string | No       | SIP status text corresponding to the status code                                                 |

**Twilio metadata** (`type: "twilio"`):

| Field  | Type   | Required | Description                                                                                                                               |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Yes      | Provider type (always `twilio`)                                                                                                           |
| `body` | object | Yes      | Twilio StatusCallback body containing call details, documented [here](https://www.twilio.com/docs/voice/api/call-resource#statuscallback) |

## Example webhook payloads

### Transcription webhook example

```json
{
  "type": "post_call_transcription",
  "event_timestamp": 1739537297,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "status": "done",
    "user_id": "user123",
    "transcript": [
      {
        "role": "agent",
        "message": "Hey there angelo. How are you?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 0,
        "conversation_turn_metrics": null
      },
      {
        "role": "user",
        "message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 2,
        "conversation_turn_metrics": null
      },
      {
        "role": "agent",
        "message": "I do not have access to fun facts about Eleven Labs. However, I can share some general information about the company. Eleven Labs is an AI voice technology platform that specializes in voice cloning and text-to-speech...",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 9,
        "conversation_turn_metrics": {
          "convai_llm_service_ttfb": {
            "elapsed_time": 0.3704247010173276
          },
          "convai_llm_service_ttf_sentence": {
            "elapsed_time": 0.5551181449554861
          }
        }
      }
    ],
    "metadata": {
      "start_time_unix_secs": 1739537297,
      "call_duration_secs": 22,
      "cost": 296,
      "deletion_settings": {
        "deletion_time_unix_secs": 1802609320,
        "deleted_logs_at_time_unix_secs": null,
        "deleted_audio_at_time_unix_secs": null,
        "deleted_transcript_at_time_unix_secs": null,
        "delete_transcript_and_pii": true,
        "delete_audio": true
      },
      "feedback": {
        "overall_score": null,
        "likes": 0,
        "dislikes": 0
      },
      "authorization_method": "authorization_header",
      "charging": {
        "dev_discount": true
      },
      "termination_reason": ""
    },
    "analysis": {
      "evaluation_criteria_results": {},
      "data_collection_results": {},
      "call_successful": "success",
      "transcript_summary": "The conversation begins with the agent asking how Angelo is, but Angelo redirects the conversation by requesting a fun fact about 11 Labs. The agent acknowledges they don't have specific fun facts about Eleven Labs but offers to provide general information about the company. They briefly describe Eleven Labs as an AI voice technology platform specializing in voice cloning and text-to-speech technology. The conversation is brief and informational, with the agent adapting to the user's request despite not having the exact information asked for."
    },
    "conversation_initiation_client_data": {
      "conversation_config_override": {
        "agent": {
          "prompt": null,
          "first_message": null,
          "language": "en"
        },
        "tts": {
          "voice_id": null
        }
      },
      "custom_llm_extra_body": {},
      "dynamic_variables": {
        "user_name": "angelo"
      }
    }
  }
}
```

### Audio webhook example

```json
{
  "type": "post_call_audio",
  "event_timestamp": 1739537319,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "full_audio": "SUQzBAAAAAAA...base64_encoded_mp3_data...AAAAAAAAAA=="
  }
}
```

### Call initiation failure webhook examples

#### Twilio metadata example

```json
{
  "type": "call_initiation_failure",
  "event_timestamp": 1759931652,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "failure_reason": "busy",
    "metadata": {
      "type": "twilio",
      "body": {
        "Called": "+441111111111",
        "ToState": "",
        "CallerCountry": "US",
        "Direction": "outbound-api",
        "Timestamp": "Wed, 08 Oct 2025 13:54:12 +0000",
        "CallbackSource": "call-progress-events",
        "SipResponseCode": "487",
        "CallerState": "WA",
        "ToZip": "",
        "SequenceNumber": "2",
        "CallSid": "CA8367245817625617832576245724",
        "To": "+441111111111",
        "CallerZip": "98631",
        "ToCountry": "GB",
        "CalledZip": "",
        "ApiVersion": "2010-04-01",
        "CalledCity": "",
        "CallStatus": "busy",
        "Duration": "0",
        "From": "+11111111111",
        "CallDuration": "0",
        "AccountSid": "AC37682153267845716245762454a",
        "CalledCountry": "GB",
        "CallerCity": "RAYMOND",
        "ToCity": "",
        "FromCountry": "US",
        "Caller": "+11111111111",
        "FromCity": "RAYMOND",
        "CalledState": "",
        "FromZip": "12345",
        "FromState": "WA"
      }
    }
  }
}
```

#### SIP metadata example

```json
{
  "type": "call_initiation_failure",
  "event_timestamp": 1759931652,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "failure_reason": "busy",
    "metadata": {
      "type": "sip",
      "body": {
        "from_number": "+441111111111",
        "to_number": "+11111111111"
        "sip_status_code": 486,
        "error_reason": "INVITE failed: sip status: 486: Busy here (SIP 486)",
        "call_sid": "d8e7f6a5-b4c3-4d5e-8f9a-0b1c2d3e4f5a",
        "sip_status": "Busy here",
        "twirp_code": "unavailable"
      }
    }
  }
}
```

## Audio webhook delivery

Audio webhooks are delivered separately from transcription webhooks and contain only the essential fields needed to identify the conversation along with the base64-encoded audio data.

<Note>
  Audio webhooks can be enabled or disabled using the "Send audio data" toggle in your webhook
  settings. This setting can be configured at both the workspace level (in ElevenAgents settings)
  and at the agent level (in individual agent webhook overrides).
</Note>

### Streaming delivery

Audio webhooks are delivered as streaming HTTP requests with the `transfer-encoding: chunked` header to handle large audio files efficiently.

### Processing audio webhooks

Since audio webhooks are delivered via chunked transfer encoding, you'll need to handle streaming data properly:

<CodeBlocks>
  ```python

  import base64
  import json
  from aiohttp import web

  async def handle_webhook(request):

      # Check if this is a chunked/streaming request
      if request.headers.get("transfer-encoding", "").lower() == "chunked":
          # Read streaming data in chunks
          chunked_body = bytearray()
          while True:
              chunk = await request.content.read(8192)  # 8KB chunks
              if not chunk:
                  break
              chunked_body.extend(chunk)

          # Parse the complete payload
          request_body = json.loads(chunked_body.decode("utf-8"))
      else:
          # Handle regular requests
          body_bytes = await request.read()
          request_body = json.loads(body_bytes.decode('utf-8'))

      # Process different webhook types
      if request_body["type"] == "post_call_transcription":
          # Handle transcription webhook with full conversation data
          handle_transcription_webhook(request_body["data"])
      elif request_body["type"] == "post_call_audio":
          # Handle audio webhook with minimal data
          handle_audio_webhook(request_body["data"])
      elif request_body["type"] == "call_initiation_failure":
          # Handle call initiation failure webhook
          handle_call_initiation_failure_webhook(request_body["data"])

      return web.json_response({"status": "ok"})

  def handle_audio_webhook(data):
      # Decode base64 audio data
      audio_bytes = base64.b64decode(data["full_audio"])

      # Save or process the audio file
      conversation_id = data["conversation_id"]
      with open(f"conversation_{conversation_id}.mp3", "wb") as f:
          f.write(audio_bytes)

  def handle_call_initiation_failure_webhook(data):
      # Handle call initiation failure events
      agent_id = data["agent_id"]
      conversation_id = data["conversation_id"]
      failure_reason = data.get("failure_reason")
      metadata = data.get("metadata", {})

      # Log the failure for monitoring
      print(f"Call failed for agent {agent_id}, conversation {conversation_id}")
      print(f"Failure reason: {failure_reason}")

      # Access provider-specific metadata
      provider_type = metadata.get("type")
      body = metadata.get("body", {})
      if provider_type == "sip":
          print(f"SIP status code: {body.get('sip_status_code')}")
          print(f"Error reason: {body.get('error_reason')}")
      elif provider_type == "twilio":
          print(f"Twilio CallSid: {body.get('CallSid')}")
          print(f"Call status: {body.get('CallStatus')}")

      # Update your system with the failure information
      # e.g., mark lead as "call_failed" in CRM

  ```

  ```javascript
  import fs from 'fs';

  app.post('/webhook/elevenlabs', (req, res) => {
    let body = '';

    // Handle chunked/streaming requests
    req.on('data', (chunk) => {
      body += chunk;
    });

    req.on('end', () => {
      try {
        const requestBody = JSON.parse(body);

        // Process different webhook types
        if (requestBody.type === 'post_call_transcription') {
          // Handle transcription webhook with full conversation data
          handleTranscriptionWebhook(requestBody.data);
        } else if (requestBody.type === 'post_call_audio') {
          // Handle audio webhook with minimal data
          handleAudioWebhook(requestBody.data);
        } else if (requestBody.type === 'call_initiation_failure') {
          // Handle call initiation failure webhook
          handleCallFailureWebhook(requestBody.data);
        }

        res.status(200).json({ status: 'ok' });
      } catch (error) {
        console.error('Error processing webhook:', error);
        res.status(400).json({ error: 'Invalid JSON' });
      }
    });
  });

  function handleAudioWebhook(data) {
    // Decode base64 audio data
    const audioBytes = Buffer.from(data.full_audio, 'base64');

    // Save or process the audio file
    const conversationId = data.conversation_id;
    fs.writeFileSync(`conversation_${conversationId}.mp3`, audioBytes);
  }

  function handleCallFailureWebhook(data) {
    // Handle call initiation failure events
    const { agent_id, conversation_id, failure_reason, metadata } = data;

    // Log the failure for monitoring
    console.log(`Call failed for agent ${agent_id}, conversation ${conversation_id}`);
    console.log(`Failure reason: ${failure_reason}`);

    // Access provider-specific metadata
    const body = metadata.body || {};
    if (metadata?.type === 'sip') {
      console.log(`SIP status code: ${body.sip_status_code}`);
      console.log(`Error reason: ${body.error_reason}`);
    } else if (metadata?.type === 'twilio') {
      console.log(`Twilio CallSid: ${body.CallSid}`);
      console.log(`Call status: ${body.CallStatus}`);
    }

    // Update your system with the failure information
    // e.g., mark lead as "call_failed" in CRM
  }
  ```
</CodeBlocks>

<Note>
  Audio webhooks can be large files, so ensure your webhook endpoint can handle streaming requests
  and has sufficient memory/storage capacity. The audio is delivered in MP3 format.
</Note>

## Use cases

### Automated call follow-ups

Post-call webhooks enable you to build automated workflows that trigger immediately after a call ends. Here are some practical applications:

#### CRM integration

Update your customer relationship management system with conversation data as soon as a call completes:

```javascript
// Example webhook handler
app.post('/webhook/elevenlabs', async (req, res) => {
  // HMAC validation code

  const { data } = req.body;

  // Extract key information
  const userId = data.metadata.user_id;
  const transcriptSummary = data.analysis.transcript_summary;
  const callSuccessful = data.analysis.call_successful;

  // Update CRM record
  await updateCustomerRecord(userId, {
    lastInteraction: new Date(),
    conversationSummary: transcriptSummary,
    callOutcome: callSuccessful,
    fullTranscript: data.transcript,
  });

  res.status(200).send('Webhook received');
});
```

### Stateful conversations

Maintain conversation context across multiple interactions by storing and retrieving state:

1. When a call starts, pass in your user id as a dynamic variable.
2. When a call ends, set up your webhook endpoint to store conversation data in your database, based on the extracted user id from the dynamic\_variables.
3. When the user calls again, you can retrieve this context and pass it to the new conversation into a \{\{previous\_topics}} dynamic variable.
4. This creates a seamless experience where the agent "remembers" previous interactions

```javascript
// Store conversation state when call ends
app.post('/webhook/elevenlabs', async (req, res) => {
  // HMAC validation code

  const { data } = req.body;
  const userId = data.metadata.user_id;

  // Store conversation state
  await db.userStates.upsert({
    userId,
    lastConversationId: data.conversation_id,
    lastInteractionTimestamp: data.metadata.start_time_unix_secs,
    conversationHistory: data.transcript,
    previousTopics: extractTopics(data.analysis.transcript_summary),
  });

  res.status(200).send('Webhook received');
});

// When initiating a new call, retrieve and use the state
async function initiateCall(userId) {
  // Get user's conversation state
  const userState = await db.userStates.findOne({ userId });

  // Start new conversation with context from previous calls
  return await elevenlabs.startConversation({
    agent_id: 'xyz',
    conversation_id: generateNewId(),
    dynamic_variables: {
      user_name: userState.name,
      previous_conversation_id: userState.lastConversationId,
      previous_topics: userState.previousTopics.join(', '),
    },
  });
}
```


# Python SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in minutes.

<Info>
  Also see the 

  [ElevenAgents overview](/docs/agents-platform/overview)
</Info>

## Installation

Install the `elevenlabs` Python package in your project:

```shell
pip install elevenlabs
# or
poetry add elevenlabs
```

If you want to use the default implementation of audio input/output you will also need the `pyaudio` extra:

```shell
pip install "elevenlabs[pyaudio]"
# or
poetry add "elevenlabs[pyaudio]"
```

<Info>
  The `pyaudio` package installation might require additional system dependencies.

  See [PyAudio package README](https://pypi.org/project/PyAudio/) for more information.

  <Tabs>
    <Tab title="Linux">
      On Debian-based systems you can install the dependencies with:

      ```shell
      sudo apt-get update
      sudo apt-get install libportaudio2 libportaudiocpp0 portaudio19-dev libasound-dev libsndfile1-dev -y
      ```
    </Tab>

    <Tab title="macOS">
      On macOS with Homebrew you can install the dependencies with:

      ```shell
      brew install portaudio
      ```
    </Tab>
  </Tabs>
</Info>

## Usage

In this example we will create a simple script that runs a conversation with the ElevenLabs Agents agent.
You can find the full code in the [ElevenLabs examples repository](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/python).

First import the necessary dependencies:

```python
import os
import signal

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
```

Next load the agent ID and API key from environment variables:

```python
agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
```

The API key is only required for non-public agents that have authentication enabled.
You don't have to set it for public agents and the code will work fine without it.

Then create the `ElevenLabs` client instance:

```python
elevenlabs = ElevenLabs(api_key=api_key)
```

Now we initialize the `Conversation` instance:

```python
conversation = Conversation(
    # API client and agent ID.
    elevenlabs,
    agent_id,

    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),

    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),

    # Simple callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),

    # Uncomment if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),

    # Uncomment if you want to receive audio alignment data with character-level timing.
    # callback_audio_alignment=lambda alignment: print(f"Alignment: {alignment.chars}"),
)
```

We are using the `DefaultAudioInterface` which uses the default system audio input/output devices for the conversation.
You can also implement your own audio interface by subclassing `elevenlabs.conversational_ai.conversation.AudioInterface`.

Now we can start the conversation. Optionally, we recommended passing in your own end user IDs to map conversations to your users.

```python
conversation.start_session(
    user_id=user_id # optional field
)
```

To get a clean shutdown when the user presses `Ctrl+C` we can add a signal handler which will call `end_session()`:

```python
signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())
```

And lastly we wait for the conversation to end and print out the conversation ID (which can be used for reviewing the conversation history and debugging):

```python
conversation_id = conversation.wait_for_session_end()
print(f"Conversation ID: {conversation_id}")
```

All that is left is to run the script and start talking to the agent:

```shell
# For public agents:
AGENT_ID=youragentid python demo.py

# For private agents:
AGENT_ID=youragentid ELEVENLABS_API_KEY=yourapikey python demo.py
```


# React SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in minutes.

<Info>
  Refer to the [ElevenAgents overview](/docs/agents-platform/overview) for an explanation of how
  ElevenAgents works.
</Info>

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/ftf-8F91bAc?rel=0&autoplay=0" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Installation

Install the package in your project through package manager.

```shell
npm install @elevenlabs/react
# or
yarn add @elevenlabs/react
# or
pnpm install @elevenlabs/react
```

## Usage

### useConversation

A React hook for managing connection and audio usage for ElevenLabs Agents.

#### Initialize conversation

First, initialize the Conversation instance.

```tsx
import { useConversation } from '@elevenlabs/react';

const conversation = useConversation();
```

Note that Agents Platform requires microphone access. Consider explaining and allowing access in your app's UI before the Conversation starts.

```js
// call after explaining to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia({ audio: true });
```

#### Options

The Conversation can be optionally initialized with certain parameters.

```tsx
const conversation = useConversation({
  /* options object */
});
```

Options include:

* **clientTools** - object definition for client tools that can be invoked by agent. [See below](#client-tools) for details.
* **overrides** - object definition conversations settings overrides. [See below](#conversation-overrides) for details.
* **textOnly** - whether the conversation should run in text-only mode. [See below](#text-only) for details.
* **serverLocation** - specify the server location (`"us"`, `"eu-residency"`, `"in-residency"`, `"global"`). Defaults to `"us"`.

#### Callbacks Overview

* **onConnect** - handler called when the conversation websocket connection is established.
* **onDisconnect** - handler called when the conversation websocket connection is ended.
* **onMessage** - handler called when a new message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM, or debug message when a debug option is enabled.
* **onError** - handler called when a error is encountered.
* **onAudio** - handler called when audio data is received.
* **onModeChange** - handler called when the conversation mode changes (speaking/listening).
* **onStatusChange** - handler called when the connection status changes.
* **onCanSendFeedbackChange** - handler called when the ability to send feedback changes.
* **onDebug** - handler called when debug information is available.
* **onUnhandledClientToolCall** - handler called when an unhandled client tool call is encountered.
* **onVadScore** - handler called when voice activity detection score changes.
* **onAudioAlignment** - handler called when audio alignment data is received, providing character-level timing information for agent speech.

##### Client Tools

Client tools are a way to enable agent to invoke client-side functionality. This can be used to trigger actions in the client, such as opening a modal or doing an API call on behalf of the user.

Client tools definition is an object of functions, and needs to be identical with your configuration within the [ElevenLabs UI](https://elevenlabs.io/app/agents), where you can name and describe different tools, as well as set up the parameters passed by the agent.

```ts
const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(text);

      return 'Message displayed';
    },
  },
});
```

In case function returns a value, it will be passed back to the agent as a response.

Note that the tool needs to be explicitly set to be blocking conversation in ElevenLabs UI for the agent to await and react to the response, otherwise agent assumes success and continues the conversation.

##### Conversation overrides

You may choose to override various settings of the conversation and set them dynamically based other user interactions.

We support overriding various settings. These settings are optional and can be used to customize the conversation experience.

The following settings are available:

```ts
const conversation = useConversation({
  overrides: {
    agent: {
      prompt: {
        prompt: 'My custom prompt',
      },
      firstMessage: 'My custom first message',
      language: 'en',
    },
    tts: {
      voiceId: 'custom voice id',
    },
    conversation: {
      textOnly: true,
    },
  },
});
```

##### Text only

If your agent is configured to run in text-only mode, i.e. it does not send or receive audio messages, you can use this flag to use a lighter version of the conversation. In that case, the user will not be asked for microphone permissions and no audio context will be created.

```ts
const conversation = useConversation({
  textOnly: true,
});
```

##### Controlled State

You can control certain aspects of the conversation state directly through the hook options:

```ts
const [micMuted, setMicMuted] = useState(false);
const [volume, setVolume] = useState(0.8);

const conversation = useConversation({
  micMuted,
  volume,
  // ... other options
});

// Update controlled state
setMicMuted(true); // This will automatically mute the microphone
setVolume(0.5); // This will automatically adjust the volume
```

##### Data residency

You can specify which ElevenLabs server region to connect to. For more information see the [data residency guide](/docs/overview/administration/data-residency).

```ts
const conversation = useConversation({
  serverLocation: 'eu-residency', // or "us", "in-residency", "global"
});
```

#### Methods

##### startSession

The `startConversation` method kicks off the WebSocket or WebRTC connection and starts using the microphone to communicate with the ElevenLabs Agents agent. The method accepts an options object, with the `signedUrl`, `conversationToken` or `agentId` option being required.

The Agent ID can be acquired through [ElevenLabs UI](https://elevenlabs.io/app/agents).

We also recommended passing in your own end user IDs to map conversations to your users.

```js
const conversation = useConversation();

// For public agents, pass in the agent ID and the connection type
const conversationId = await conversation.startSession({
  agentId: '<your-agent-id>',
  connectionType: 'webrtc', // either "webrtc" or "websocket"
  userId: '<your-end-user-id>', // optional field
});
```

For public agents (i.e. agents that don't have authentication enabled), only the `agentId` is required.

In case the conversation requires authorization, use the REST API to generate signed links for a WebSocket connection or a conversation token for a WebRTC connection.

`startSession` returns a promise resolving a `conversationId`. The value is a globally unique conversation ID you can use to identify separate conversations.

<Tabs>
  <Tab title="WebSocket connection">
    ```js maxLines=0
    // Node.js server

    app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
      const response = await fetch(
        `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
        {
          headers: {
            // Requesting a signed url requires your ElevenLabs API key
            // Do NOT expose your API key to the client!
            "xi-api-key": process.env.ELEVENLABS_API_KEY,
          },
        }
      );

      if (!response.ok) {
        return res.status(500).send("Failed to get signed URL");
      }

      const body = await response.json();
      res.send(body.signed_url);
    });
    ```

    ```js
    // Client

    const response = await fetch("/signed-url", yourAuthHeaders);
    const signedUrl = await response.text();

    const conversation = await Conversation.startSession({
      signedUrl,
      connectionType: "websocket",
    });
    ```
  </Tab>

  <Tab title="WebRTC connection">
    ```js maxLines=0
    // Node.js server

    app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
      const response = await fetch(
        `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
        {
          headers: {
            // Requesting a conversation token requires your ElevenLabs API key
            // Do NOT expose your API key to the client!
            "xi-api-key": process.env.ELEVENLABS_API_KEY,
          }
        }
      );

      if (!response.ok) {
        return res.status(500).send("Failed to get conversation token");
      }

      const body = await response.json();
      res.send(body.token);
    );
    ```

    ```js
    // Client

    const response = await fetch("/conversation-token", yourAuthHeaders);
    const conversationToken = await response.text();

    const conversation = await Conversation.startSession({
      conversationToken,
      connectionType: "webrtc",
    });
    ```
  </Tab>
</Tabs>

##### endSession

A method to manually end the conversation. The method will disconnect and end the conversation.

```js
await conversation.endSession();
```

##### setVolume

Sets the output volume of the conversation. Accepts an object with a `volume` field between 0 and 1.

```js
await conversation.setVolume({ volume: 0.5 });
```

##### status

A React state containing the current status of the conversation.

```js
const { status } = useConversation();
console.log(status); // "connected" or "disconnected"
```

##### isSpeaking

A React state containing information on whether the agent is currently speaking. This is useful for indicating agent status in your UI.

```js
const { isSpeaking } = useConversation();
console.log(isSpeaking); // boolean
```

##### sendUserMessage

Sends a text message to the agent.

Can be used to let the user type in the message instead of using the microphone. Unlike `sendContextualUpdate`, this will be treated as a user message and will prompt the agent to take its turn in the conversation.

```js
const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");

return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue("");
      }}
    >
      SEND
    </button>
  </>
);
```

##### sendContextualUpdate

Sends contextual information to the agent that won't trigger a response.

```js
const { sendContextualUpdate } = useConversation();

sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);
```

##### sendFeedback

Provide feedback on the conversation quality. This helps improve the agent's performance.

```js
const { sendFeedback } = useConversation();

sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback
```

##### sendUserActivity

Notifies the agent about user activity to prevent interruptions. Useful for when the user is actively using the app and the agent should pause speaking, i.e. when the user is typing in a chat.

The agent will pause speaking for \~2 seconds after receiving this signal.

```js
const { sendUserActivity } = useConversation();

// Call this when user is typing to prevent interruption
sendUserActivity();
```

##### canSendFeedback

A React state indicating whether feedback can be submitted for the current conversation.

```js
const { canSendFeedback } = useConversation();

// Use this to conditionally show feedback UI
{
  canSendFeedback && (
    <FeedbackButtons
      onLike={() => conversation.sendFeedback(true)}
      onDislike={() => conversation.sendFeedback(false)}
    />
  );
}
```

##### changeInputDevice

Switch the audio input device during an active voice conversation. This method is only available for voice conversations.

```js
// Change to a specific input device
await conversation.changeInputDevice({
  sampleRate: 16000,
  format: 'pcm',
  preferHeadphonesForIosDevices: true,
  inputDeviceId: 'your-device-id', // Optional: specific device ID
});
```

##### changeOutputDevice

Switch the audio output device during an active voice conversation. This method is only available for voice conversations.

```js
// Change to a specific output device
await conversation.changeOutputDevice({
  sampleRate: 16000,
  format: 'pcm',
  outputDeviceId: 'your-device-id', // Optional: specific device ID
});
```

<Note>
  Device switching only works for voice conversations. If no specific `deviceId` is provided, the
  browser will use its default device selection. You can enumerate available devices using the
  [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)
  API.
</Note>

##### getId

Returns the current conversation ID.

```js
const { getId } = useConversation();
const conversationId = getId();
console.log(conversationId); // e.g., "conv_abc123"
```

##### getInputVolume / getOutputVolume

Methods that return the current input/output volume levels (0-1 scale).

```js
const { getInputVolume, getOutputVolume } = useConversation();
const inputLevel = getInputVolume();
const outputLevel = getOutputVolume();
```

##### getInputByteFrequencyData / getOutputByteFrequencyData

Methods that return `Uint8Array`s containing the current input/output frequency data. See [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) for more information.

```js
const { getInputByteFrequencyData, getOutputByteFrequencyData } = useConversation();
const inputFrequencyData = getInputByteFrequencyData();
const outputFrequencyData = getOutputByteFrequencyData();
```

<Note>
  These methods are only available for voice conversations. In WebRTC mode the audio is hardcoded to
  use `pcm_48000`, meaning any visualization using the returned data might show different patterns
  to WebSocket connections.
</Note>

##### sendMCPToolApprovalResult

Sends approval result for MCP (Model Context Protocol) tool calls.

```js
const { sendMCPToolApprovalResult } = useConversation();

// Approve a tool call
sendMCPToolApprovalResult('tool_call_id_123', true);

// Reject a tool call
sendMCPToolApprovalResult('tool_call_id_123', false);
```


# React Native SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in minutes for React Native apps.

<Info>
  Refer to the [ElevenAgents overview](/docs/agents-platform/overview) for an explanation of how
  ElevenAgents works.
</Info>

## Installation

Install the package and its dependencies in your React Native project.

```shell
npm install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc livekit-client
```

<Tip>
  An example app using this SDK with Expo can be found
  [here](https://github.com/elevenlabs/packages/tree/main/examples/react-native-expo)
</Tip>

## Requirements

* React Native with LiveKit dependencies
* Microphone permissions configured for your platform
* Expo compatibility (development builds only)

<Warning>
  This SDK was designed and built for use with the Expo framework. Due to its dependency on
  LiveKit's WebRTC implementation, it requires development builds and cannot be used with Expo Go.
</Warning>

## Setup

### Provider Setup

Wrap your app with the `ElevenLabsProvider` to enable ElevenAgents functionality.

```tsx
import { ElevenLabsProvider } from '@elevenlabs/react-native';
import React from 'react';

function App() {
  return (
    <ElevenLabsProvider>
      <YourAppComponents />
    </ElevenLabsProvider>
  );
}
```

## Usage

### useConversation

A React Native hook for managing connection and audio usage for ElevenLabs Agents.

#### Initialize conversation

First, initialize the Conversation instance within a component that's wrapped by `ElevenLabsProvider`.

```tsx
import { useConversation } from '@elevenlabs/react-native';
import React from 'react';

function ConversationComponent() {
  const conversation = useConversation();

  // Your component logic here
}
```

Note that ElevenAgents requires microphone access. Consider explaining and requesting permissions in your app's UI before the Conversation starts, especially on mobile platforms where permission management is crucial.

#### Options

The Conversation can be initialized with certain options:

```tsx
const conversation = useConversation({
  onConnect: () => console.log('Connected to conversation'),
  onDisconnect: () => console.log('Disconnected from conversation'),
  onMessage: (message) => console.log('Received message:', message),
  onError: (error) => console.error('Conversation error:', error),
  onModeChange: (mode) => console.log('Conversation mode changed:', mode),
  onStatusChange: (prop) => console.log('Conversation status changed:', prop.status),
  onCanSendFeedbackChange: (prop) =>
    console.log('Can send feedback changed:', prop.canSendFeedback),
  onUnhandledClientToolCall: (params) => console.log('Unhandled client tool call:', params),
  onAudioAlignment: (alignment) => console.log('Alignment data received:', alignment),
});
```

* **onConnect** - Handler called when the conversation WebRTC connection is established.
* **onDisconnect** - Handler called when the conversation WebRTC connection is ended.
* **onMessage** - Handler called when a new message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM, or debug messages.
* **onError** - Handler called when an error is encountered.
* **onModeChange** - Handler called when the conversation mode changes. This is useful for indicating whether the agent is speaking or listening.
* **onStatusChange** - Handler called when the conversation status changes.
* **onCanSendFeedbackChange** - Handler called when the ability to send feedback changes.
* **onUnhandledClientToolCall** - Handler called when an unhandled client tool call is encountered.
* **onAudioAlignment** - Handler called when audio alignment data is received, providing character-level timing information for agent speech.

<Warning>
  Not all client events are enabled by default for an agent. If you have enabled a callback but
  aren't seeing events come through, ensure that your ElevenLabs agent has the corresponding event
  enabled. You can do this in the "Advanced" tab of the agent settings in the ElevenLabs dashboard.
</Warning>

#### Methods

##### startSession

The `startSession` method kicks off the WebRTC connection and starts using the microphone to communicate with the ElevenLabs Agents agent. The method accepts a configuration object with the `agentId` being conditionally required based on whether the agent is public or private.

###### Public agents

For public agents (i.e. agents that don't have authentication enabled), only the `agentId` is required. The Agent ID can be acquired through the [ElevenLabs UI](https://elevenlabs.io/app/agents).

```tsx
const conversation = useConversation();

// For public agents, pass in the agent ID
const startConversation = async () => {
  await conversation.startSession({
    agentId: 'your-agent-id',
  });
};
```

###### Private agents

For private agents, you must pass in a `conversationToken` obtained from the ElevenLabs API. Generating this token requires an ElevenLabs API key.

<Tip>
  The 

  `conversationToken`

   is valid for 10 minutes.
</Tip>

```ts maxLines={0}
// Node.js server

app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.ELEVENLABS_API_KEY,
      }
    }
  );

  if (!response.ok) {
    return res.status(500).send("Failed to get conversation token");
  }

  const body = await response.json();
  res.send(body.token);
);
```

Then, pass the token to the `startSession` method. Note that only the `conversationToken` is required for private agents.

```tsx
const conversation = useConversation();

const response = await fetch('/conversation-token', yourAuthHeaders);
const conversationToken = await response.text();

// For private agents, pass in the conversation token
const startConversation = async () => {
  await conversation.startSession({
    conversationToken,
  });
};
```

You can optionally pass a user ID to identify the user in the conversation. This can be your own customer identifier. This will be included in the conversation initiation data sent to the server.

```tsx
const startConversation = async () => {
  await conversation.startSession({
    agentId: 'your-agent-id',
    userId: 'your-user-id',
  });
};
```

##### endSession

A method to manually end the conversation. The method will disconnect and end the conversation.

```tsx
const endConversation = async () => {
  await conversation.endSession();
};
```

##### sendUserMessage

Send a text message to the agent during an active conversation.

```tsx
const sendMessage = async () => {
  await conversation.sendUserMessage('Hello, how can you help me?');
};
```

#### sendContextualUpdate

Sends contextual information to the agent that won't trigger a response.

```tsx
const sendContextualUpdate = async () => {
  await conversation.sendContextualUpdate(
    'User navigated to the profile page. Consider this for next response.'
  );
};
```

##### sendFeedback

Provide feedback on the conversation quality. This helps improve the agent's performance.

```tsx
const provideFeedback = async (liked: boolean) => {
  await conversation.sendFeedback(liked);
};
```

##### sendUserActivity

Notifies the agent about user activity to prevent interruptions. Useful for when the user is actively using the app and the agent should pause speaking, i.e. when the user is typing in a chat.

The agent will pause speaking for \~2 seconds after receiving this signal.

```tsx
const signalActivity = async () => {
  await conversation.sendUserActivity();
};
```

#### Properties

##### status

A React state containing the current status of the conversation.

```tsx
const { status } = useConversation();
console.log(status); // "connected" or "disconnected"
```

##### isSpeaking

A React state containing information on whether the agent is currently speaking. This is useful for indicating agent status in your UI.

```tsx
const { isSpeaking } = useConversation();
console.log(isSpeaking); // boolean
```

##### canSendFeedback

A React state indicating whether feedback can be submitted for the current conversation.

```tsx
const { canSendFeedback } = useConversation();

// Use this to conditionally show feedback UI
{
  canSendFeedback && (
    <FeedbackButtons
      onLike={() => conversation.sendFeedback(true)}
      onDislike={() => conversation.sendFeedback(false)}
    />
  );
}
```

##### getId

Retrieves the conversation ID.

```tsx
const conversationId = conversation.getId();
console.log(conversationId); // e.g., "conv_9001k1zph3fkeh5s8xg9z90swaqa"
```

##### setMicMuted

Mutes/unmutes the microphone.

```tsx
// Mute the microphone
conversation.setMicMuted(true);

// Unmute the microphone
conversation.setMicMuted(false);
```

## Example Implementation

Here's a complete example of a React Native component using the ElevenLabs Agents SDK:

```tsx
import { ElevenLabsProvider, useConversation } from '@elevenlabs/react-native';
import React, { useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';

function ConversationScreen() {
  const [isConnected, setIsConnected] = useState(false);

  const conversation = useConversation({
    onConnect: () => {
      console.log('Connected to conversation');
      setIsConnected(true);
    },
    onDisconnect: () => {
      console.log('Disconnected from conversation');
      setIsConnected(false);
    },
    onMessage: (message) => {
      console.log('Message received:', message);
    },
    onError: (error) => {
      console.error('Conversation error:', error);
    },
  });

  const startConversation = async () => {
    try {
      await conversation.startSession({
        agentId: 'your-agent-id',
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  };

  const endConversation = async () => {
    try {
      await conversation.endSession();
    } catch (error) {
      console.error('Failed to end conversation:', error);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.status}>Status: {conversation.status}</Text>

      <Text style={styles.speaking}>
        Agent is {conversation.isSpeaking ? 'speaking' : 'not speaking'}
      </Text>

      <TouchableOpacity
        style={[styles.button, isConnected && styles.buttonActive]}
        onPress={isConnected ? endConversation : startConversation}
      >
        <Text style={styles.buttonText}>
          {isConnected ? 'End Conversation' : 'Start Conversation'}
        </Text>
      </TouchableOpacity>

      {conversation.canSendFeedback && (
        <View style={styles.feedbackContainer}>
          <TouchableOpacity
            style={styles.feedbackButton}
            onPress={() => conversation.sendFeedback(true)}
          >
            <Text>👍</Text>
          </TouchableOpacity>
          <TouchableOpacity
            style={styles.feedbackButton}
            onPress={() => conversation.sendFeedback(false)}
          >
            <Text>👎</Text>
          </TouchableOpacity>
        </View>
      )}
    </View>
  );
}

function App() {
  return (
    <ElevenLabsProvider>
      <ConversationScreen />
    </ElevenLabsProvider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  status: {
    fontSize: 16,
    marginBottom: 10,
  },
  speaking: {
    fontSize: 14,
    marginBottom: 20,
    color: '#666',
  },
  button: {
    backgroundColor: '#007AFF',
    paddingHorizontal: 20,
    paddingVertical: 10,
    borderRadius: 8,
    marginBottom: 20,
  },
  buttonActive: {
    backgroundColor: '#FF3B30',
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: '600',
  },
  feedbackContainer: {
    flexDirection: 'row',
    gap: 10,
  },
  feedbackButton: {
    backgroundColor: '#F2F2F7',
    padding: 10,
    borderRadius: 8,
  },
});

export default App;
```

## Platform-Specific Considerations

### iOS

Ensure microphone permissions are properly configured in your `Info.plist`:

```xml
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to enable voice conversations with AI agents.</string>
```

### Android

Add microphone permissions to your `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

Consider requesting runtime permissions before starting a conversation:

```tsx
import { PermissionsAndroid, Platform } from 'react-native';

const requestMicrophonePermission = async () => {
  if (Platform.OS === 'android') {
    const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO, {
      title: 'Microphone Permission',
      message: 'This app needs microphone access to enable voice conversations.',
      buttonNeutral: 'Ask Me Later',
      buttonNegative: 'Cancel',
      buttonPositive: 'OK',
    });
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  }
  return true;
};
```


# JavaScript SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in minutes.

<Info>
  Also see the 

  [ElevenAgents overview](/docs/agents-platform/overview)
</Info>

## Installation

Install the package in your project through package manager.

```shell
npm install @elevenlabs/client
# or
yarn add @elevenlabs/client
# or
pnpm install @elevenlabs/client
```

## Usage

This library is primarily meant for development in vanilla JavaScript projects, or as a base for libraries tailored to specific frameworks.
It is recommended to check whether your specific framework has its own library.
However, you can use this library in any JavaScript-based project.

### Initialize conversation

First, initialize the Conversation instance:

```js
const conversation = await Conversation.startSession(options);
```

This will kick off the websocket connection and start using microphone to communicate with the ElevenLabs Agents agent. Consider explaining and allowing microphone access in your apps UI before the Conversation kicks off:

```js
// call after explaining to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia({ audio: true });
```

#### Session configuration

The options passed to `startSession` specify how the session is established. Conversations can be started with public or private agents.

##### Public agents

Agents that don't require any authentication can be used to start a conversation by using the agent ID and the connection type. The agent ID can be acquired through the [ElevenLabs UI](https://elevenlabs.io/app/conversational-ai).

For public agents, you can use the ID directly:

```js
const conversation = await Conversation.startSession({
  agentId: '<your-agent-id>',
  connectionType: 'webrtc', // 'websocket' is also accepted
});
```

##### Private agents

If the conversation requires authorization, you will need to add a dedicated endpoint to your server that will either request a signed url (if using the WebSockets connection type) or a conversation token (if using WebRTC) using the [ElevenLabs API](https://elevenlabs.io/docs/overview/intro) and pass it back to the client.

Here's an example for a WebSocket connection:

```js maxLines=0
// Node.js server

app.get('/signed-url', yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      method: 'GET',
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.XI_API_KEY,
      },
    }
  );

  if (!response.ok) {
    return res.status(500).send('Failed to get signed URL');
  }

  const body = await response.json();
  res.send(body.signed_url);
});
```

```js
// Client

const response = await fetch('/signed-url', yourAuthHeaders);
const signedUrl = await response.text();

const conversation = await Conversation.startSession({
  signedUrl,
  connectionType: 'websocket',
});
```

Here's an example for WebRTC:

```js maxLines=0
// Node.js server

app.get('/conversation-token', yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.ELEVENLABS_API_KEY,
      },
    }
  );

  if (!response.ok) {
    return res.status(500).send('Failed to get conversation token');
  }

  const body = await response.json();
  res.send(body.token);
});
```

Once you have the token, providing it to `startSession` will initiate the conversation using WebRTC.

```js
// Client

const response = await fetch('/conversation-token', yourAuthHeaders);
const conversationToken = await response.text();

const conversation = await Conversation.startSession({
  conversationToken,
  connectionType: 'webrtc',
});
```

#### Optional callbacks

The options passed to `startSession` can also be used to register optional callbacks:

* **onConnect** - handler called when the conversation websocket connection is established.
* **onDisconnect** - handler called when the conversation websocket connection is ended.
* **onMessage** - handler called when a new text message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM. Primarily used for handling conversation transcription.
* **onError** - handler called when an error is encountered.
* **onStatusChange** - handler called whenever connection status changes. Can be `connected`, `connecting` and `disconnected` (initial).
* **onModeChange** - handler called when a status changes, eg. agent switches from `speaking` to `listening`, or the other way around.
* **onCanSendFeedbackChange** - handler called when sending feedback becomes available or unavailable.
* **onAudioAlignment** - handler called when audio alignment data is received, providing character-level timing information for agent speech.

<Warning>
  Not all client events are enabled by default for an agent. If you have enabled a callback but
  aren't seeing events come through, ensure that your ElevenLabs agent has the corresponding event
  enabled. You can do this in the "Advanced" tab of the agent settings in the ElevenLabs dashboard.
</Warning>

#### Return value

`startSession` returns a `Conversation` instance that can be used to control the session. The method will throw an error if the session cannot be established. This can happen if the user denies microphone access, or if the connection
fails.

**endSession**

A method to manually end the conversation. The method will end the conversation and disconnect from websocket.
Afterwards the conversation instance will be unusable and can be safely discarded.

```js
await conversation.endSession();
```

**getId**

A method returning the conversation ID.

```js
const id = conversation.getId();
```

**setVolume**

A method to set the output volume of the conversation. Accepts object with volume field between 0 and 1.

```js
await conversation.setVolume({ volume: 0.5 });
```

**getInputVolume / getOutputVolume**

Methods that return the current input/output volume on a scale from `0` to `1` where `0` is -100 dB and `1` is -30 dB.

```js
const inputVolume = await conversation.getInputVolume();
const outputVolume = await conversation.getOutputVolume();
```

**sendFeedback**

A method for sending binary feedback to the agent. The method accepts a boolean value, where `true` represents positive feedback and `false` negative feedback.

Feedback is always correlated to the most recent agent response and can be sent only once per response.

You can listen to `onCanSendFeedbackChange` to know if feedback can be sent at the given moment.

```js
conversation.sendFeedback(true); // positive feedback
conversation.sendFeedback(false); // negative feedback
```

**sendContextualUpdate**

A method to send contextual updates to the agent. This can be used to inform the agent about user actions that are not directly related to the conversation, but may influence the agent's responses.

```js
conversation.sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);
```

**sendUserMessage**

Sends a text message to the agent.

Can be used to let the user type in the message instead of using the microphone. Unlike `sendContextualUpdate`, this will be treated as a user message and will prompt the agent to take its turn in the conversation.

```js
sendButton.addEventListener('click', (e) => {
  conversation.sendUserMessage(textInput.value);
  textInput.value = '';
});
```

**sendUserActivity**

Notifies the agent about user activity.

The agent will not attempt to speak for at least 2 seconds after the user activity is detected.

This can be used to prevent the agent from interrupting the user when they are typing.

```js
textInput.addEventListener('input', () => {
  conversation.sendUserActivity();
});
```

**setMicMuted**

A method to mute/unmute the microphone.

```js
// Mute the microphone
conversation.setMicMuted(true);

// Unmute the microphone
conversation.setMicMuted(false);
```

**changeInputDevice**

Allows you to change the audio input device during an active voice conversation. This method is only available for voice conversations.

<Note>
  In WebRTC mode the input format and sample rate are hardcoded to `pcm` and `48000` respectively.
  Changing those values when changing the input device is a no-op.
</Note>

```js
const conversation = await Conversation.startSession({
  agentId: '<your-agent-id>',
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  inputDeviceId: 'your-device-id',
});

// Change to a specific input device
await conversation.changeInputDevice({
  sampleRate: 16000,
  format: 'pcm',
  preferHeadphonesForIosDevices: true,
  inputDeviceId: 'your-device-id',
});
```

If the device ID is invalid, the default device will be used instead.

**changeOutputDevice**

Allows you to change the audio output device during an active voice conversation. This method is only available for voice conversations.

<Note>
  In WebRTC mode the output format and sample rate are hardcoded to `pcm` and `48000` respectively.
  Changing those values when changing the output device is a no-op.
</Note>

```js
const conversation = await Conversation.startSession({
  agentId: '<your-agent-id>',
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  outputDeviceId: 'your-device-id',
});

// Change to a specific output device
await conversation.changeOutputDevice({
  sampleRate: 16000,
  format: 'pcm',
  outputDeviceId: 'your-device-id',
});
```

<Note>
  Device switching only works for voice conversations. If no specific `deviceId` is provided, the
  browser will use its default device selection. You can enumerate available devices using the
  [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)
  API.
</Note>

**getInputByteFrequencyData / getOutputByteFrequencyData**

Methods that return `Uint8Array`s containing the current input/output frequency data. See [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) for more information.

<Note>
  These methods are only available for voice conversations. In WebRTC mode the audio is hardcoded to
  use `pcm_48000`, meaning any visualization using the returned data might show different patterns
  to WebSocket connections.
</Note>


# Kotlin SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in minutes for Android apps.

<Info>
  Refer to the [ElevenAgents overview](/docs/agents-platform/overview) for an explanation of how
  ElevenAgents works.
</Info>

## Installation

Add the ElevenLabs SDK to your Android project by including the following dependency in your app-level `build.gradle` file:

```kotlin build.gradle.kts
dependencies {
    // ElevenLabs Agents SDK (Android)
    implementation("io.elevenlabs:elevenlabs-android:<latest>")

    // Kotlin coroutines, AndroidX, etc., as needed by your app
}
```

<Tip>
  An example Android app using this SDK can be found
  [here](https://github.com/elevenlabs/elevenlabs-android/tree/main/example-app)
</Tip>

## Requirements

* Android API level 21 (Android 5.0) or higher
* Internet permission for API calls
* Microphone permission for voice input
* Network security configuration for HTTPS calls

## Setup

### Manifest Configuration

Add the necessary permissions to your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
```

### Runtime Permissions

For Android 6.0 (API level 23) and higher, you must request microphone permission at runtime:

```kotlin
import android.Manifest
import android.content.pm.PackageManager
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

private fun requestMicrophonePermission() {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO)
        != PackageManager.PERMISSION_GRANTED) {

        if (ActivityCompat.shouldShowRequestPermissionRationale(this, Manifest.permission.RECORD_AUDIO)) {
            // Show explanation to the user
            showPermissionExplanationDialog()
        } else {
            ActivityCompat.requestPermissions(
                this,
                arrayOf(Manifest.permission.RECORD_AUDIO),
                MICROPHONE_PERMISSION_REQUEST_CODE
            )
        }
    }
}
```

## Usage

Initialize the ElevenLabs SDK in your `Application` class or main activity:

Start a conversation session with either:

* Public agent: pass `agentId`
* Private agent: pass `conversationToken` provisioned from your backend (never expose your API key to the client).

```kotlin
import io.elevenlabs.ConversationClient
import io.elevenlabs.ConversationConfig
import io.elevenlabs.ConversationSession
import io.elevenlabs.ClientTool
import io.elevenlabs.ClientToolResult

// Start a public agent session (token generated for you)
val config = ConversationConfig(
    agentId = "<your_public_agent_id>", // OR conversationToken = "<token>"
    userId = "your-user-id",
    // Optional callbacks
    onConnect = { conversationId ->
        // Called when the conversation is connected and returns the conversation ID. You can access conversationId via session.getId() too
    },
    onMessage = { source, messageJson ->
        // Raw JSON messages from data channel; useful for logging/telemetry
    },
    onModeChange = { mode ->
        // "speaking" | "listening" — drive UI indicators
    },
    onStatusChange = { status ->
        // "connected" | "connecting" | "disconnected"
    },
    onCanSendFeedbackChange = { canSend ->
        // Enable/disable thumbs up/down buttons for feedback reporting
    },
    onUnhandledClientToolCall = { call ->
        // Agent requested a client tool not registered on the device
    },
    onVadScore = { score ->
        // Voice Activity Detection score, range from 0 to 1 where higher values indicate higher confidence of speech
    },
    onAudioAlignment = { alignment ->
        // Character-level timing data for synchronized text display
        val chars = alignment["chars"] as? List<*>
        val startTimes = alignment["char_start_times_ms"] as? List<*>
        val durations = alignment["char_durations_ms"] as? List<*>
        Log.d("ExampleApp", "Audio alignment: $chars")
    },
    // List of client tools the agent can invoke
    clientTools = mapOf(
        "logMessage" to object : ClientTool {
            override suspend fun execute(parameters: Map<String, Any>): ClientToolResult {
                val message = parameters["message"] as? String

                Log.d("ExampleApp", "[INFO] Client Tool Log: $message")
                return ClientToolResult.success("Message logged successfully")
            }
        }
    ),
)

// In an Activity context
val session: ConversationSession = ConversationClient.startSession(config, this)
```

Note that ElevenAgents requires microphone access. Consider explaining and requesting permissions in your app's UI before the conversation starts, especially on Android 6.0+ where runtime permissions are required.

<Note>
  If a tool is configured with `expects_response=false` on the server, return `null` from `execute`
  to skip sending a tool result back to the agent.
</Note>

## Public vs Private Agents

* **Public agents** (no auth): Initialize with `agentId` in `ConversationConfig`. The SDK requests a conversation token from ElevenLabs without needing an API key on device.
* **Private agents** (auth): Initialize with `conversationToken` in `ConversationConfig`. Your server requests a conversation token from ElevenLabs using your ElevenLabs API key.

<Error>
  Never embed API keys in clients. They can be easily extracted and used maliciously.
</Error>

## Client Tools

Register client tools to allow the agent to call local capabilities on the device.

```kotlin
val config = ConversationConfig(
    agentId = "<public_agent>",
    clientTools = mapOf(
        "logMessage" to object : io.elevenlabs.ClientTool {
            override suspend fun execute(parameters: Map<String, Any>): io.elevenlabs.ClientToolResult? {
                val message = parameters["message"] as? String ?: return io.elevenlabs.ClientToolResult.failure("Missing 'message'")

                android.util.Log.d("ClientTool", "Log: $message")
                return null // No response needed for fire-and-forget tools
            }
        }
    )
)
```

When the agent issues a `client_tool_call`, the SDK executes the matching tool and responds with a `client_tool_result`. If the tool is not registered, `onUnhandledClientToolCall` is invoked and a failure result is returned to the agent (if a response is expected).

### Callbacks Overview

* **onConnect** - Called when the WebRTC connection is established. Returns the conversation ID.
* **onMessage** - Called when a new message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM, or debug messages. Provides source (`"ai"` or `"user"`) and raw JSON message.
* **onModeChange** - Called when the conversation mode changes. This is useful for indicating whether the agent is speaking (`"speaking"`) or listening (`"listening"`).
* **onStatusChange** - Called when the conversation status changes (`"connected"`, `"connecting"`, or `"disconnected"`).
* **onCanSendFeedbackChange** - Called when the ability to send feedback changes. Enables/disables feedback buttons.
* **onUnhandledClientToolCall** - Called when the agent requests a client tool that is not registered on the device.
* **onVadScore** - Called when the voice activity detection score changes. Range from 0 to 1 where higher values indicate higher confidence of speech.
* **onAudioAlignment** - Called when audio alignment data is received, providing character-level timing information for agent speech.

<Warning>
  Not all client events are enabled by default for an agent. If you have enabled a callback but
  aren't seeing events come through, ensure that your ElevenLabs agent has the corresponding event
  enabled. You can do this in the "Advanced" tab of the agent settings in the ElevenLabs dashboard.
</Warning>

### Methods

#### startSession

The `startSession` method initiates the WebRTC connection and starts using the microphone to communicate with the ElevenLabs Agents agent.

##### Public agents

For public agents (i.e. agents that don't have authentication enabled), only the `agentId` is required. The Agent ID can be acquired through the [ElevenLabs UI](https://elevenlabs.io/app/agents).

```kotlin
val session = ConversationClient.startSession(
    config = ConversationConfig(
        agentId = "your-agent-id"
    ),
    context = this
)
```

##### Private agents

For private agents, you must pass in a `conversationToken` obtained from the ElevenLabs API. Generating this token requires an ElevenLabs API key.

<Tip>
  The 

  `conversationToken`

   is valid for 10 minutes.
</Tip>

```typescript maxLines=0
// Server-side token generation (Node.js example)

app.get('/conversation-token', yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.ELEVENLABS_API_KEY,
      },
    }
  );

  if (!response.ok) {
    return res.status(500).send('Failed to get conversation token');
  }

  const body = await response.json();
  res.send(body.token);
});
```

Then, pass the token to the `startSession` method. Note that only the `conversationToken` is required for private agents.

```kotlin

// Get conversation token from your server
val conversationToken = fetchConversationTokenFromServer()

// For private agents, pass in the conversation token
val session = ConversationClient.startSession(
    config = ConversationConfig(
        conversationToken = conversationToken
    ),
    context = this
)
```

You can optionally pass a user ID to identify the user in the conversation. This can be your own customer identifier. This will be included in the conversation initiation data sent to the server.

```kotlin
val session = ConversationClient.startSession(
    config = ConversationConfig(
        agentId = "your-agent-id",
        userId = "your-user-id"
    ),
    context = this
)
```

#### endSession

A method to manually end the conversation. The method will disconnect and end the conversation.

```kotlin
session.endSession()
```

#### sendUserMessage

Send a text message to the agent during an active conversation. This will trigger a response from the agent.

```kotlin
session.sendUserMessage("Hello, how can you help me?")
```

#### sendContextualUpdate

Sends contextual information to the agent that won't trigger a response.

```kotlin
session.sendContextualUpdate(
    "User navigated to the profile page. Consider this for next response."
)
```

#### sendFeedback

Provide feedback on the conversation quality. This helps improve the agent's performance. Use `onCanSendFeedbackChange` to enable your thumbs up/down UI when feedback is allowed.

```kotlin
// Positive feedback
session.sendFeedback(true)

// Negative feedback
session.sendFeedback(false)
```

#### sendUserActivity

Notifies the agent about user activity to prevent interruptions. Useful for when the user is actively using the app and the agent should pause speaking, i.e. when the user is typing in a chat.

The agent will pause speaking for \~2 seconds after receiving this signal.

```kotlin
session.sendUserActivity()
```

#### getId

Get the conversation ID.

```kotlin
val conversationId = session.getId()
Log.d("Conversation", "Conversation ID: $conversationId")
// e.g., "conv_123"
```

#### Mute/ Unmute

```kotlin
session.toggleMute()
session.setMicMuted(true)   // mute
session.setMicMuted(false)  // unmute
```

Observe `session.isMuted` to update the UI label between "Mute" and "Unmute".

### Properties

#### status

Get the current status of the conversation.

```kotlin
val status = session.status
Log.d("Conversation", "Current status: $status")
// Values: DISCONNECTED, CONNECTING, CONNECTED
```

## ProGuard / R8

If you shrink/obfuscate, ensure Gson models and LiveKit are kept. Example rules (adjust as needed):

```proguard
-keep class io.elevenlabs.** { *; }
-keep class io.livekit.** { *; }
-keepattributes *Annotation*
```

## Troubleshooting

* Ensure microphone permission is granted at runtime
* If reconnect hangs, verify your app calls `session.endSession()` and that you start a new session instance before reconnecting
* For emulators, verify audio input/output routes are working; physical devices tend to behave more reliably

## Example Implementation

For an example implementation, see the example app in the [ElevenLabs Android SDK repository](https://github.com/elevenlabs/elevenlabs-android/tree/main/example-app). The app demonstrates:

* One‑tap connect/disconnect
* Speaking/listening indicator
* Feedback buttons with UI enable/disable
* Typing indicator via `sendUserActivity()`
* Contextual and user messages from an input
* Microphone mute/unmute button


# Swift SDK

> ElevenAgents SDK: deploy customized, interactive voice agents in your Swift applications.

<Info>
  Check out our [complete Swift quickstart project](https://github.com/elevenlabs/voice-starterkit-swift) to get started quickly with a full working example.
</Info>

## Installation

Add the ElevenLabs Swift SDK to your project using Swift Package Manager:

<Steps>
  <Step title="Add the Package Dependency">
    ```swift
    dependencies: [ .package(url: "https://github.com/elevenlabs/elevenlabs-swift-sdk.git",
    from: "2.0.0") ]
    ```

    Or using Xcode:

    1. Open your project in Xcode
    2. Go to `File` > `Add Package Dependencies...`
    3. Enter the repository URL: `https://github.com/elevenlabs/elevenlabs-swift-sdk.git`
    4. Select version 2.0.0 or later
  </Step>

  <Step title="Import the SDK">
    ```swift
    import ElevenLabs
    ```
  </Step>
</Steps>

<Warning>
  Ensure you add `NSMicrophoneUsageDescription` to your Info.plist to explain microphone access to
  users. The SDK requires iOS 14.0+ / macOS 11.0+ and Swift 5.9+.
</Warning>

## Quick Start

Get started with a simple conversation in just a few lines. Optionally, We recommended passing in your own end user id's to map conversations to your users.

```swift
import ElevenLabs

// Start a conversation with your agent
let conversation = try await ElevenLabs.startConversation(
    agentId: "your-agent-id",
    userId: "your-end-user-id",
    config: ConversationConfig()
)

// Observe conversation state and messages
conversation.$state
    .sink { state in
        print("Connection state: \(state)")
    }
    .store(in: &cancellables)

conversation.$messages
    .sink { messages in
        for message in messages {
            print("\(message.role): \(message.content)")
        }
    }
    .store(in: &cancellables)

// Send messages and control the conversation
try await conversation.sendMessage("Hello!")
try await conversation.toggleMute()
await conversation.endConversation()
```

## Authentication

There are two ways to authenticate and start a conversation:

<Tabs>
  <Tab title="Public Agents">
    For public agents, use the agent ID directly:

    ```swift
    let conversation = try await ElevenLabs.startConversation(
        agentId: "your-public-agent-id",
        config: ConversationConfig()
    )
    ```
  </Tab>

  <Tab title="Private Agents">
    For private agents, use a conversation token obtained from your backend:

    ```swift
    // Get token from your backend (never store API keys in your app)
    let token = try await fetchConversationToken()
    let conversation = try await ElevenLabs.startConversation(
        auth: .conversationToken(token),
        config: ConversationConfig()
    )
    ```

    <Warning>
      Never store your ElevenLabs API key in your mobile app. Always use a backend service to generate conversation tokens.
    </Warning>
  </Tab>
</Tabs>

## Core Features

### Reactive Conversation Management

The SDK provides a modern `Conversation` class with `@Published` properties for reactive UI updates:

```swift
@MainActor
class ConversationManager: ObservableObject {
    @Published var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()

    func startConversation(agentId: String) async throws {
        let config = ConversationConfig(
            conversationOverrides: ConversationOverrides(textOnly: false)
        )

        conversation = try await ElevenLabs.startConversation(
            agentId: agentId,
            config: config
        )

        setupObservers()
    }

    private func setupObservers() {
        guard let conversation else { return }

        // Monitor connection state
        conversation.$state
            .sink { state in print("State: \(state)") }
            .store(in: &cancellables)

        // Monitor messages
        conversation.$messages
            .sink { messages in print("Messages: \(messages.count)") }
            .store(in: &cancellables)
    }
}
```

### Voice and Text Modes

```swift
// Voice conversation (default)
let voiceConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: false)
)

// Text-only conversation
let textConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: true)
)
```

### Audio Controls

```swift
// Microphone control
try await conversation.toggleMute()
try await conversation.setMuted(true)

// Check microphone state
let isMuted = conversation.isMuted

// Access audio tracks for advanced use cases
let inputTrack = conversation.inputTrack
let agentAudioTrack = conversation.agentAudioTrack
```

### Client Tools

Client Tools allow you to register custom functions that can be called by your AI agent during conversations. The new SDK provides improved parameter handling and error management.

#### Handling Tool Calls

Handle tool calls from your agent with full parameter support:

```swift
private func handleToolCall(_ toolCall: ClientToolCallEvent) async {
    do {
        let parameters = try toolCall.getParameters()
        let result = await executeClientTool(
            name: toolCall.toolName,
            parameters: parameters
        )

        if toolCall.expectsResponse {
            try await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: result
            )
        } else {
            conversation?.markToolCallCompleted(toolCall.toolCallId)
        }
    } catch {
        // Handle tool execution errors
        if toolCall.expectsResponse {
            try? await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: ["error": error.localizedDescription],
                isError: true
            )
        }
    }
}

// Example tool implementation
func executeClientTool(name: String, parameters: [String: Any]) async -> [String: Any] {
    switch name {
    case "get_weather":
        guard let location = parameters["location"] as? String else {
            return ["error": "Missing location parameter"]
        }
        // Fetch weather data
        return ["temperature": "22°C", "condition": "Sunny"]

    case "send_email":
        guard let recipient = parameters["recipient"] as? String,
              let subject = parameters["subject"] as? String else {
            return ["error": "Missing required parameters"]
        }
        // Send email logic
        return ["status": "sent", "messageId": "12345"]

    default:
        return ["error": "Unknown tool: \(name)"]
    }
}
```

<Info>
  Remember to setup your agent with the client-tools in the ElevenLabs UI. See the [Client Tools
  documentation](/docs/agents-platform/customization/tools/client-tools) for setup instructions.
</Info>

### Connection State Management

Monitor the conversation state to handle different connection phases:

```swift
conversation.$state
    .sink { state in
        switch state {
        case .idle:
            // Not connected
            break
        case .connecting:
            // Show connecting indicator
            break
        case .active(let callInfo):
            // Connected to agent: \(callInfo.agentId)
            break
        case .ended(let reason):
            // Handle disconnection: \(reason)
            break
        case .error(let error):
            // Handle error: \(error)
            break
        }
    }
    .store(in: &cancellables)
```

### Agent State Monitoring

Track when the agent is listening or speaking:

```swift
conversation.$agentState
    .sink { state in
        switch state {
        case .listening:
            // Agent is listening, show listening indicator
            break
        case .speaking:
            // Agent is speaking, show speaking indicator
            break
        }
    }
    .store(in: &cancellables)
```

### Message Handling

Send text messages and monitor the conversation:

```swift
// Send a text message
try await conversation.sendMessage("Hello, how can you help me today?")

// Monitor all messages in the conversation
conversation.$messages
    .sink { messages in
        for message in messages {
            switch message.role {
            case .user:
                print("User: \(message.content)")
            case .agent:
                print("Agent: \(message.content)")
            }
        }
    }
    .store(in: &cancellables)
```

### Audio Alignment

Monitor character-level timing data for synchronized text display:

```swift
// Using the callback
let config = ConversationConfig(
    onAudioAlignment: { alignment in
        // Character-level timing data
        for (index, char) in alignment.chars.enumerated() {
            let startMs = alignment.charStartTimesMs[index]
            let durationMs = alignment.charDurationsMs[index]
            print("'\(char)' at \(startMs)ms for \(durationMs)ms")
        }
    }
)

// Or observe the published property
conversation.$latestAudioAlignment
    .compactMap { $0 }
    .sink { alignment in
        // Handle alignment updates
    }
    .store(in: &cancellables)
```

### Session Management

```swift
// End the conversation
await conversation.endConversation()

// Check if conversation is active
let isActive = conversation.state.isActive
```

## SwiftUI Integration

Here's a comprehensive SwiftUI example using the new SDK:

```swift
import SwiftUI
import ElevenLabs
import Combine

struct ConversationView: View {
    @StateObject private var viewModel = ConversationViewModel()

    var body: some View {
        VStack(spacing: 20) {
            // Connection status
            Text(viewModel.connectionStatus)
                .font(.headline)
                .foregroundColor(viewModel.isConnected ? .green : .red)

            // Chat messages
            ScrollView {
                LazyVStack(alignment: .leading, spacing: 8) {
                    ForEach(viewModel.messages, id: \.id) { message in
                        MessageBubble(message: message)
                    }
                }
            }
            .frame(maxHeight: 400)

            // Controls
            HStack(spacing: 16) {
                Button(viewModel.isConnected ? "End" : "Start") {
                    Task {
                        if viewModel.isConnected {
                            await viewModel.endConversation()
                        } else {
                            await viewModel.startConversation()
                        }
                    }
                }
                .buttonStyle(.borderedProminent)

                Button(viewModel.isMuted ? "Unmute" : "Mute") {
                    Task { await viewModel.toggleMute() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)

                Button("Send Message") {
                    Task { await viewModel.sendTestMessage() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)
            }

            // Agent state indicator
            if viewModel.isConnected {
                HStack {
                    Circle()
                        .fill(viewModel.agentState == .speaking ? .blue : .gray)
                        .frame(width: 10, height: 10)
                    Text(viewModel.agentState == .speaking ? "Agent speaking" : "Agent listening")
                        .font(.caption)
                }
            }
        }
        .padding()
    }
}

struct MessageBubble: View {
    let message: Message

    var body: some View {
        HStack {
            if message.role == .user { Spacer() }

            VStack(alignment: .leading) {
                Text(message.role == .user ? "You" : "Agent")
                    .font(.caption)
                    .foregroundColor(.secondary)
                Text(message.content)
                    .padding()
                    .background(message.role == .user ? Color.blue : Color.gray.opacity(0.3))
                    .foregroundColor(message.role == .user ? .white : .primary)
                    .cornerRadius(12)
            }

            if message.role == .agent { Spacer() }
        }
    }
}

@MainActor
class ConversationViewModel: ObservableObject {
    @Published var messages: [Message] = []
    @Published var isConnected = false
    @Published var isMuted = false
    @Published var agentState: AgentState = .listening
    @Published var connectionStatus = "Disconnected"

    private var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()

    func startConversation() async {
        do {
            conversation = try await ElevenLabs.startConversation(
                agentId: "your-agent-id",
                config: ConversationConfig()
            )
            setupObservers()
        } catch {
            print("Failed to start conversation: \(error)")
            connectionStatus = "Failed to connect"
        }
    }

    func endConversation() async {
        await conversation?.endConversation()
        conversation = nil
        cancellables.removeAll()
    }

    func toggleMute() async {
        try? await conversation?.toggleMute()
    }

    func sendTestMessage() async {
        try? await conversation?.sendMessage("Hello from the app!")
    }

    private func setupObservers() {
        guard let conversation else { return }

        conversation.$messages
            .assign(to: &$messages)

        conversation.$state
            .map { state in
                switch state {
                case .idle: return "Disconnected"
                case .connecting: return "Connecting..."
                case .active: return "Connected"
                case .ended: return "Ended"
                case .error: return "Error"
                }
            }
            .assign(to: &$connectionStatus)

        conversation.$state
            .map { $0.isActive }
            .assign(to: &$isConnected)

        conversation.$isMuted
            .assign(to: &$isMuted)

        conversation.$agentState
            .assign(to: &$agentState)
    }
}
```


# WebSocket

> Create real-time, interactive voice conversations with AI agents

<Note>
  This documentation is for developers integrating directly with the ElevenLabs WebSocket API. For
  convenience, consider using [the official SDKs provided by
  ElevenLabs](/docs/agents-platform/libraries/python).
</Note>

The [ElevenAgents](https://elevenlabs.io/agents) WebSocket API enables real-time, interactive voice conversations with AI agents. By establishing a WebSocket connection, you can send audio input and receive audio responses in real-time, creating life-like conversational experiences.

<Note>
  Endpoint: 

  `wss://api.elevenlabs.io/v1/convai/conversation?agent_id={agent_id}`
</Note>

## Authentication

### Using Agent ID

For public agents, you can directly use the `agent_id` in the WebSocket URL without additional authentication:

```bash
wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-agent-id>
```

### Using a signed URL

For private agents or conversations requiring authorization, obtain a signed URL from your server, which securely communicates with the ElevenLabs API using your API key.

### Example using cURL

**Request:**

```bash
curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=<your-agent-id>" \
     -H "xi-api-key: <your-api-key>"
```

**Response:**

```json
{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-agent-id>&token=<token>"
}
```

<Warning>
  Never expose your ElevenLabs API key on the client side.
</Warning>

## WebSocket events

### Client to server events

The following events can be sent from the client to the server:

<AccordionGroup>
  <Accordion title="Contextual Updates">
    Send non-interrupting contextual information to update the conversation state. This allows you to provide additional context without disrupting the ongoing conversation flow.

    ```javascript
    {
      "type": "contextual_update",
      "text": "User clicked on pricing page"
    }
    ```

    **Use cases:**

    * Updating user status or preferences
    * Providing environmental context
    * Adding background information
    * Tracking user interface interactions

    **Key points:**

    * Does not interrupt current conversation flow
    * Updates are incorporated as tool calls in conversation history
    * Helps maintain context without breaking the natural dialogue

    <Note>
      Contextual updates are processed asynchronously and do not require a direct response from the server.
    </Note>
  </Accordion>
</AccordionGroup>

<Card title="WebSocket API Reference" icon="code" iconPosition="left" href="/docs/agents-platform/api-reference/eleven-agents/websocket">
  See the ElevenLabs Agents WebSocket API reference documentation for detailed message structures,
  parameters, and examples.
</Card>

## Next.js implementation example

This example demonstrates how to implement a WebSocket-based conversational agent client in Next.js using the ElevenLabs WebSocket API.

<Note>
  While this example uses the `voice-stream` package for microphone input handling, you can
  implement your own solution for capturing and encoding audio. The focus here is on demonstrating
  the WebSocket connection and event handling with the ElevenLabs API.
</Note>

<Steps>
  <Step title="Install required dependencies">
    First, install the necessary packages:

    ```bash
    npm install voice-stream
    ```

    The `voice-stream` package handles microphone access and audio streaming, automatically encoding the audio in base64 format as required by the ElevenLabs API.

    <Note>
      This example uses Tailwind CSS for styling. To add Tailwind to your Next.js project:

      ```bash
      npm install -D tailwindcss postcss autoprefixer
      npx tailwindcss init -p
      ```

      Then follow the [official Tailwind CSS setup guide for Next.js](https://tailwindcss.com/docs/guides/nextjs).

      Alternatively, you can replace the className attributes with your own CSS styles.
    </Note>
  </Step>

  <Step title="Create WebSocket types">
    Define the types for WebSocket events:

    ```typescript app/types/websocket.ts
    type BaseEvent = {
      type: string;
    };

    type UserTranscriptEvent = BaseEvent & {
      type: "user_transcript";
      user_transcription_event: {
        user_transcript: string;
      };
    };

    type AgentResponseEvent = BaseEvent & {
      type: "agent_response";
      agent_response_event: {
        agent_response: string;
      };
    };

    type AgentResponseCorrectionEvent = BaseEvent & {
      type: "agent_response_correction";
      agent_response_correction_event: {
        original_agent_response: string;
        corrected_agent_response: string;
      };
    };

    type AudioResponseEvent = BaseEvent & {
      type: "audio";
      audio_event: {
        audio_base_64: string;
        event_id: number;
        alignment: {
          chars: string[];
          char_durations_ms: number[];
          char_start_times_ms: number[];
        };
      };
    };

    type InterruptionEvent = BaseEvent & {
      type: "interruption";
      interruption_event: {
        reason: string;
      };
    };

    type PingEvent = BaseEvent & {
      type: "ping";
      ping_event: {
        event_id: number;
        ping_ms?: number;
      };
    };

    export type ElevenLabsWebSocketEvent =
      | UserTranscriptEvent
      | AgentResponseEvent
      | AgentResponseCorrectionEvent
      | AudioResponseEvent
      | InterruptionEvent
      | PingEvent;
    ```
  </Step>

  <Step title="Create WebSocket hook">
    Create a custom hook to manage the WebSocket connection:

    ```typescript app/hooks/useAgentConversation.ts
    'use client';

    import { useCallback, useEffect, useRef, useState } from 'react';
    import { useVoiceStream } from 'voice-stream';
    import type { ElevenLabsWebSocketEvent } from '../types/websocket';

    const sendMessage = (websocket: WebSocket, request: object) => {
      if (websocket.readyState !== WebSocket.OPEN) {
        return;
      }
      websocket.send(JSON.stringify(request));
    };

    export const useAgentConversation = () => {
      const websocketRef = useRef<WebSocket>(null);
      const [isConnected, setIsConnected] = useState<boolean>(false);

      const { startStreaming, stopStreaming } = useVoiceStream({
        onAudioChunked: (audioData) => {
          if (!websocketRef.current) return;
          sendMessage(websocketRef.current, {
            user_audio_chunk: audioData,
          });
        },
      });

      const startConversation = useCallback(async () => {
        if (isConnected) return;

        const websocket = new WebSocket("wss://api.elevenlabs.io/v1/convai/conversation");

        websocket.onopen = async () => {
          setIsConnected(true);
          sendMessage(websocket, {
            type: "conversation_initiation_client_data",
          });
          await startStreaming();
        };

        websocket.onmessage = async (event) => {
          const data = JSON.parse(event.data) as ElevenLabsWebSocketEvent;

          // Handle ping events to keep connection alive
          if (data.type === "ping") {
            setTimeout(() => {
              sendMessage(websocket, {
                type: "pong",
                event_id: data.ping_event.event_id,
              });
            }, data.ping_event.ping_ms);
          }

          if (data.type === "user_transcript") {
            const { user_transcription_event } = data;
            console.log("User transcript", user_transcription_event.user_transcript);
          }

          if (data.type === "agent_response") {
            const { agent_response_event } = data;
            console.log("Agent response", agent_response_event.agent_response);
          }

          if (data.type === "agent_response_correction") {
            const { agent_response_correction_event } = data;
            console.log("Agent response correction", agent_response_correction_event.corrected_agent_response);
          }

          if (data.type === "interruption") {
            // Handle interruption
          }

          if (data.type === "audio") {
            const { audio_event } = data;
            // Implement your own audio playback system here
            // Note: You'll need to handle audio queuing to prevent overlapping
            // as the WebSocket sends audio events in chunks
          }
        };

        websocketRef.current = websocket;

        websocket.onclose = async () => {
          websocketRef.current = null;
          setIsConnected(false);
          stopStreaming();
        };
      }, [startStreaming, isConnected, stopStreaming]);

      const stopConversation = useCallback(async () => {
        if (!websocketRef.current) return;
        websocketRef.current.close();
      }, []);

      useEffect(() => {
        return () => {
          if (websocketRef.current) {
            websocketRef.current.close();
          }
        };
      }, []);

      return {
        startConversation,
        stopConversation,
        isConnected,
      };
    };
    ```
  </Step>

  <Step title="Create the conversation component">
    Create a component to use the WebSocket hook:

    ```typescript app/components/Conversation.tsx
    'use client';

    import { useCallback } from 'react';
    import { useAgentConversation } from '../hooks/useAgentConversation';

    export function Conversation() {
      const { startConversation, stopConversation, isConnected } = useAgentConversation();

      const handleStart = useCallback(async () => {
        try {
          await navigator.mediaDevices.getUserMedia({ audio: true });
          await startConversation();
        } catch (error) {
          console.error('Failed to start conversation:', error);
        }
      }, [startConversation]);

      return (
        <div className="flex flex-col items-center gap-4">
          <div className="flex gap-2">
            <button
              onClick={handleStart}
              disabled={isConnected}
              className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
            >
              Start Conversation
            </button>
            <button
              onClick={stopConversation}
              disabled={!isConnected}
              className="px-4 py-2 bg-red-500 text-white rounded disabled:bg-gray-300"
            >
              Stop Conversation
            </button>
          </div>
          <div className="flex flex-col items-center">
            <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
          </div>
        </div>
      );
    }
    ```
  </Step>
</Steps>

## Next steps

1. **Audio Playback**: Implement your own audio playback system using Web Audio API or a library. Remember to handle audio queuing to prevent overlapping as the WebSocket sends audio events in chunks.
2. **Error Handling**: Add retry logic and error recovery mechanisms
3. **UI Feedback**: Add visual indicators for voice activity and connection status

## Latency management

To ensure smooth conversations, implement these strategies:

* **Adaptive Buffering:** Adjust audio buffering based on network conditions.
* **Jitter Buffer:** Implement a jitter buffer to smooth out variations in packet arrival times.
* **Ping-Pong Monitoring:** Use ping and pong events to measure round-trip time and adjust accordingly.

## Security best practices

* Rotate API keys regularly and use environment variables to store them.
* Implement rate limiting to prevent abuse.
* Clearly explain the intention when prompting users for microphone access.
* Optimized Chunking: Tweak the audio chunk duration to balance latency and efficiency.

## Additional resources

* [ElevenLabs Agents Documentation](/docs/agents-platform/overview)
* [ElevenLabs Agents SDKs](/docs/agents-platform/libraries/python)


# Next.JS

> Learn how to create a web application that enables voice conversations with ElevenLabs AI agents

This tutorial will guide you through creating a web client that can interact with a ElevenLabs agent. You'll learn how to implement real-time voice conversations, allowing users to speak with an AI agent that can listen, understand, and respond naturally using voice synthesis.

## What You'll Need

1. An ElevenLabs agent created following [this guide](/docs/agents-platform/quickstart)
2. `npm` installed on your local system.
3. We'll use Typescript for this tutorial, but you can use Javascript if you prefer.

<Note>
  Looking for a complete example? Check out our [Next.js demo on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/nextjs).
</Note>

<Frame background="subtle">
  ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c1bc26a84d079cebcdfe6b4eb602bd27476d5afc92419e9ddfb92b755ca8058e/assets/images/conversational-ai/nextjs-guide.png)
</Frame>

## Setup

<Steps>
  <Step title="Create a new Next.js project">
    Open a terminal window and run the following command:

    ```bash
    npm create next-app my-conversational-agent
    ```

    It will ask you some questions about how to build your project. We'll follow the default suggestions for this tutorial.
  </Step>

  <Step title="Navigate to project directory">
    ```shell
    cd my-conversational-agent
    ```
  </Step>

  <Step title="Install the ElevenLabs dependency">
    ```shell
    npm install @elevenlabs/react
    ```
  </Step>

  <Step title="Test the setup">
    Run the following command to start the development server and open the provided URL in your browser:

    ```shell
    npm run dev
    ```

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/537e2c5609df75b2fd15bf3a37c86da75410de053dfb0c76267a72d7b8d9914a/assets/images/conversational-ai/nextjs-splash.png)
    </Frame>
  </Step>
</Steps>

## Implement ElevenLabs Agents

<Steps>
  <Step title="Create the conversation component">
    Create a new file `app/components/conversation.tsx`:

    ```tsx app/components/conversation.tsx
    'use client';

    import { useConversation } from '@elevenlabs/react';
    import { useCallback } from 'react';

    export function Conversation() {
      const conversation = useConversation({
        onConnect: () => console.log('Connected'),
        onDisconnect: () => console.log('Disconnected'),
        onMessage: (message) => console.log('Message:', message),
        onError: (error) => console.error('Error:', error),
      });


      const startConversation = useCallback(async () => {
        try {
          // Request microphone permission
          await navigator.mediaDevices.getUserMedia({ audio: true });

          // Start the conversation with your agent
          await conversation.startSession({
            agentId: 'YOUR_AGENT_ID', // Replace with your agent ID
            userId: 'YOUR_CUSTOMER_USER_ID', // Optional field for tracking your end user IDs
            connectionType: 'webrtc', // either "webrtc" or "websocket"
          });

        } catch (error) {
          console.error('Failed to start conversation:', error);
        }
      }, [conversation]);

      const stopConversation = useCallback(async () => {
        await conversation.endSession();
      }, [conversation]);

      return (
        <div className="flex flex-col items-center gap-4">
          <div className="flex gap-2">
            <button
              onClick={startConversation}
              disabled={conversation.status === 'connected'}
              className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
            >
              Start Conversation
            </button>
            <button
              onClick={stopConversation}
              disabled={conversation.status !== 'connected'}
              className="px-4 py-2 bg-red-500 text-white rounded disabled:bg-gray-300"
            >
              Stop Conversation
            </button>
          </div>

          <div className="flex flex-col items-center">
            <p>Status: {conversation.status}</p>
            <p>Agent is {conversation.isSpeaking ? 'speaking' : 'listening'}</p>
          </div>
        </div>
      );
    }
    ```
  </Step>

  <Step title="Update the main page">
    Replace the contents of `app/page.tsx` with:

    ```tsx app/page.tsx
    import { Conversation } from './components/conversation';

    export default function Home() {
      return (
        <main className="flex min-h-screen flex-col items-center justify-between p-24">
          <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm">
            <h1 className="text-4xl font-bold mb-8 text-center">
              ElevenLabs Agents
            </h1>
            <Conversation />
          </div>
        </main>
      );
    }
    ```
  </Step>
</Steps>

<Accordion title="(Optional) Authenticate the agents with a signed URL">
  <Note>
    This authentication step is only required for private agents. If you're using a public agent, you
    can skip this section and directly use the `agentId` in the `startSession` call.
  </Note>

  If you're using a private agent that requires authentication, you'll need to generate
  a signed URL from your server. This section explains how to set this up.

  ### What You'll Need

  1. An ElevenLabs account and API key. Sign up [here](https://elevenlabs.io/app/sign-up).

  <Steps>
    <Step title="Create environment variables">
      Create a `.env.local` file in your project root:

      ```yaml .env.local
      ELEVENLABS_API_KEY=your-api-key-here
      NEXT_PUBLIC_AGENT_ID=your-agent-id-here
      ```

      <Warning>
        1. Make sure to add `.env.local` to your `.gitignore` file to prevent accidentally committing sensitive credentials to version control.
        2. Never expose your API key in the client-side code. Always keep it secure on the server.
      </Warning>
    </Step>

    <Step title="Create an API route">
      Create a new file `app/api/get-signed-url/route.ts`:

      ```tsx app/api/get-signed-url/route.ts
      import { NextResponse } from 'next/server';

      export async function GET() {
        try {
          const response = await fetch(
            `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.NEXT_PUBLIC_AGENT_ID}`,
            {
              headers: {
                'xi-api-key': process.env.ELEVENLABS_API_KEY!,
              },
            }
          );

          if (!response.ok) {
            throw new Error('Failed to get signed URL');
          }

          const data = await response.json();
          return NextResponse.json({ signedUrl: data.signed_url });
        } catch (error) {
          return NextResponse.json(
            { error: 'Failed to generate signed URL' },
            { status: 500 }
          );
        }
      }
      ```
    </Step>

    <Step title="Update the Conversation component">
      Modify your `conversation.tsx` to fetch and use the signed URL:

      ```tsx app/components/conversation.tsx {5-12,19,23}
      // ... existing imports ...

      export function Conversation() {
        // ... existing conversation setup ...
        const getSignedUrl = async (): Promise<string> => {
          const response = await fetch("/api/get-signed-url");
          if (!response.ok) {
            throw new Error(`Failed to get signed url: ${response.statusText}`);
          }
          const { signedUrl } = await response.json();
          return signedUrl;
        };

        const startConversation = useCallback(async () => {
          try {
            // Request microphone permission
            await navigator.mediaDevices.getUserMedia({ audio: true });

            const signedUrl = await getSignedUrl();

            // Start the conversation with your signed url
            await conversation.startSession({
              signedUrl,
            });

          } catch (error) {
            console.error('Failed to start conversation:', error);
          }
        }, [conversation]);

        // ... rest of the component ...
      }
      ```

      <Warning>
        Signed URLs expire after a short period. However, any conversations initiated before expiration will continue uninterrupted. In a production environment, implement proper error handling and URL refresh logic for starting new conversations.
      </Warning>
    </Step>
  </Steps>
</Accordion>

## Next Steps

Now that you have a basic implementation, you can:

1. Add visual feedback for voice activity
2. Implement error handling and retry logic
3. Add a chat history display
4. Customize the UI to match your brand

<Info>
  For more advanced features and customization options, check out the
  [@elevenlabs/react](https://www.npmjs.com/package/@elevenlabs/react) package.
</Info>


# Vite (Javascript)

> Learn how to create a web application that enables voice conversations with ElevenLabs AI agents

This tutorial will guide you through creating a web client that can interact with a ElevenLabs agent. You'll learn how to implement real-time voice conversations, allowing users to speak with an AI agent that can listen, understand, and respond naturally using voice synthesis.

<Note>
  Looking to build with React/Next.js? Check out our [Next.js
  guide](/docs/agents-platform/guides/quickstarts/next-js)
</Note>

## What You'll Need

1. An ElevenLabs agent created following [this guide](/docs/agents-platform/quickstart)
2. `npm` installed on your local system
3. Basic knowledge of JavaScript

<Note>
  Looking for a complete example? Check out our [Vanilla JS demo on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/javascript).
</Note>

## Project Setup

<Steps>
  <Step title="Create a Project Directory">
    Open a terminal and create a new directory for your project:

    ```bash
    mkdir elevenlabs-conversational-ai
    cd elevenlabs-conversational-ai
    ```
  </Step>

  <Step title="Initialize npm and Install Dependencies">
    Initialize a new npm project and install the required packages:

    ```bash
    npm init -y
    npm install vite @elevenlabs/client
    ```
  </Step>

  <Step title="Set up Basic Project Structure">
    Add this to your `package.json`:

    ```json package.json {4}
    {
        "scripts": {
            ...
            "dev:frontend": "vite"
        }
    }
    ```

    Create the following file structure:

    ```shell {2,3}
    elevenlabs-conversational-ai/
    ├── index.html
    ├── script.js
    ├── package-lock.json
    ├── package.json
    └── node_modules
    ```
  </Step>
</Steps>

## Implementing the Voice Chat Interface

<Steps>
  <Step title="Create the HTML Interface">
    In `index.html`, set up a simple user interface:

    <Frame background="subtle">
      ![](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5ad9dea65eddc50beaf444e5d319dc5094df0f4183e50f7ed01900394b3ff9d2/assets/images/conversational-ai/vite-guide.png)
    </Frame>

    ```html index.html
    <!DOCTYPE html>
    <html lang="en">
        <head>
            <meta charset="UTF-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>ElevenLabs Agents</title>
        </head>
        <body style="font-family: Arial, sans-serif; text-align: center; padding: 50px;">
            <h1>ElevenLabs Agents</h1>
            <div style="margin-bottom: 20px;">
                <button id="startButton" style="padding: 10px 20px; margin: 5px;">Start Conversation</button>
                <button id="stopButton" style="padding: 10px 20px; margin: 5px;" disabled>Stop Conversation</button>
            </div>
            <div style="font-size: 18px;">
                <p>Status: <span id="connectionStatus">Disconnected</span></p>
                <p>Agent is <span id="agentStatus">listening</span></p>
            </div>
            <script type="module" src="../images/script.js"></script>
        </body>
    </html>
    ```
  </Step>

  <Step title="Implement the Conversation Logic">
    In `script.js`, implement the functionality:

    ```javascript script.js
    import { Conversation } from '@elevenlabs/client';

    const startButton = document.getElementById('startButton');
    const stopButton = document.getElementById('stopButton');
    const connectionStatus = document.getElementById('connectionStatus');
    const agentStatus = document.getElementById('agentStatus');

    let conversation;

    async function startConversation() {
        try {
            // Request microphone permission
            await navigator.mediaDevices.getUserMedia({ audio: true });

            // Start the conversation
            conversation = await Conversation.startSession({
                agentId: 'YOUR_AGENT_ID', // Replace with your agent ID
                onConnect: () => {
                    connectionStatus.textContent = 'Connected';
                    startButton.disabled = true;
                    stopButton.disabled = false;
                },
                onDisconnect: () => {
                    connectionStatus.textContent = 'Disconnected';
                    startButton.disabled = false;
                    stopButton.disabled = true;
                },
                onError: (error) => {
                    console.error('Error:', error);
                },
                onModeChange: (mode) => {
                    agentStatus.textContent = mode.mode === 'speaking' ? 'speaking' : 'listening';
                },
            });
        } catch (error) {
            console.error('Failed to start conversation:', error);
        }
    }

    async function stopConversation() {
        if (conversation) {
            await conversation.endSession();
            conversation = null;
        }
    }

    startButton.addEventListener('click', startConversation);
    stopButton.addEventListener('click', stopConversation);
    ```
  </Step>

  <Step title="Start the frontend server">
    ```shell
    npm run dev:frontend
    ```
  </Step>
</Steps>

<Note>
  Make sure to replace 

  `'YOUR_AGENT_ID'`

   with your actual agent ID from ElevenLabs.
</Note>

<Accordion title="(Optional) Authenticate with a Signed URL">
  <Note>
    This authentication step is only required for private agents. If you're using a public agent, you can skip this section and directly use the `agentId` in the `startSession` call.
  </Note>

  <Steps>
    <Step title="Create Environment Variables">
      Create a `.env` file in your project root:

      ```env .env
      ELEVENLABS_API_KEY=your-api-key-here
      AGENT_ID=your-agent-id-here
      ```

      <Warning>
        Make sure to add `.env` to your `.gitignore` file to prevent accidentally committing sensitive credentials.
      </Warning>
    </Step>

    <Step title="Setup the Backend">
      1. Install additional dependencies:

      ```bash
      npm install express cors dotenv
      ```

      2. Create a new folder called `backend`:

      ```shell {2}
      elevenlabs-conversational-ai/
      ├── backend
      ...
      ```
    </Step>

    <Step title="Create the Server">
      ```javascript backend/server.js
      require("dotenv").config();

      const express = require("express");
      const cors = require("cors");

      const app = express();
      app.use(cors());
      app.use(express.json());

      const PORT = process.env.PORT || 3001;

      app.get("/api/get-signed-url", async (req, res) => {
          try {
              const response = await fetch(
                  `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
                  {
                      headers: {
                          "xi-api-key": process.env.ELEVENLABS_API_KEY,
                      },
                  }
              );

              if (!response.ok) {
                  throw new Error("Failed to get signed URL");
              }

              const data = await response.json();
              res.json({ signedUrl: data.signed_url });
          } catch (error) {
              console.error("Error:", error);
              res.status(500).json({ error: "Failed to generate signed URL" });
          }
      });

      app.listen(PORT, () => {
          console.log(`Server running on http://localhost:${PORT}`);
      });
      ```
    </Step>

    <Step title="Update the Client Code">
      Modify your `script.js` to fetch and use the signed URL:

      ```javascript script.js {2-10,16,19,20}
      // ... existing imports and variables ...

      async function getSignedUrl() {
          const response = await fetch('http://localhost:3001/api/get-signed-url');
          if (!response.ok) {
              throw new Error(`Failed to get signed url: ${response.statusText}`);
          }
          const { signedUrl } = await response.json();
          return signedUrl;
      }

      async function startConversation() {
          try {
              await navigator.mediaDevices.getUserMedia({ audio: true });

              const signedUrl = await getSignedUrl();

              conversation = await Conversation.startSession({
                  signedUrl,
                  // agentId has been removed...
                  onConnect: () => {
                      connectionStatus.textContent = 'Connected';
                      startButton.disabled = true;
                      stopButton.disabled = false;
                  },
                  onDisconnect: () => {
                      connectionStatus.textContent = 'Disconnected';
                      startButton.disabled = false;
                      stopButton.disabled = true;
                  },
                  onError: (error) => {
                      console.error('Error:', error);
                  },
                  onModeChange: (mode) => {
                      agentStatus.textContent = mode.mode === 'speaking' ? 'speaking' : 'listening';
                  },
              });
          } catch (error) {
              console.error('Failed to start conversation:', error);
          }
      }

      // ... rest of the code ...
      ```

      <Warning>
        Signed URLs expire after a short period. However, any conversations initiated before expiration will continue uninterrupted. In a production environment, implement proper error handling and URL refresh logic for starting new conversations.
      </Warning>
    </Step>

    <Step title="Update the package.json">
      ```json package.json {4,5}
      {
          "scripts": {
              ...
              "dev:backend": "node backend/server.js",
              "dev": "npm run dev:frontend & npm run dev:backend"
          }
      }
      ```
    </Step>

    <Step title="Run the Application">
      Start the application with:

      ```bash
      npm run dev
      ```
    </Step>
  </Steps>
</Accordion>

## Next Steps

Now that you have a basic implementation, you can:

1. Add visual feedback for voice activity
2. Implement error handling and retry logic
3. Add a chat history display
4. Customize the UI to match your brand

<Info>
  For more advanced features and customization options, check out the
  [@elevenlabs/client](https://www.npmjs.com/package/@elevenlabs/client) package.
</Info>


# Chat Mode

> Configure your agent for text-only conversations with chat mode

<Info>
  Chat mode allows your agents to act as chat agents, ie to have text-only conversations without
  audio input/output. This is useful for building chat interfaces, testing agents, or when audio is
  not required.
</Info>

## Overview

There are two main ways to enable chat mode:

1. **Agent Configuration**: Configure your agent for text-only mode when creating it via the API
2. **Runtime Overrides**: Use SDK overrides to enforce text-only conversations programmatically

This guide covers both approaches and how to implement chat mode across different SDKs.

## Creating Text-Only Agents

You can configure an agent for text-only mode when creating it via the API. This sets the default behavior for all conversations with that agent.

<CodeBlocks>
  ```python
  from elevenlabs import ConversationalConfig, ConversationConfig, ElevenLabs

  client = ElevenLabs(
      api_key="YOUR_API_KEY",
  )

  # Create agent with text-only configuration
  agent = client.conversational_ai.agents.create(
      name="My Chat Agent",
      conversation_config=ConversationalConfig(
          conversation=ConversationConfig(
              text_only=True
          )
      ),
  )
  print(agent)
  ```

  ```javascript
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

  const client = new ElevenLabsClient({ apiKey: 'YOUR_API_KEY' });

  // Create agent with text-only configuration
  const agent = await client.conversationalAi.agents.create({
    name: 'My Chat Agent',
    conversationConfig: {
      conversation: {
        textOnly: true,
      },
    },
  });

  console.log(agent);
  ```
</CodeBlocks>

<Info>
  For complete API reference and all available configuration options, see the [text only field in
  Create Agent API
  documentation](/docs/api-reference/agents/create#request.body.conversation_config.conversation.text_only).
</Info>

1. **Agent Configuration**: Configure your agent for text-only mode when creating it via the API
2. **Runtime Overrides**: Use SDK overrides to enforce text-only conversations programmatically

This guide covers both approaches and how to implement chat mode across different SDKs.

## Runtime Overrides for Text-Only Mode

To enable chat mode at runtime using overrides (rather than configuring at the agent level), you can use the `textOnly` override in your conversation configuration:

<CodeBlocks>
  ```python
  from elevenlabs.client import ElevenLabs
  from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData

  # Configure for text-only mode with proper structure
  conversation_override = {
      "conversation": {
          "text_only": True
      }
  }

  config = ConversationInitiationData(
      conversation_config_override=conversation_override
  )

  conversation = Conversation(
      elevenlabs,
      agent_id,
      requires_auth=bool(api_key),
      config=config,
      # Important: Ensure agent_response callback is set
      callback_agent_response=lambda response: print(f"Agent: {response}"),
      callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
  )

  conversation.start_session()
  ```

  ```javascript
  const conversation = await Conversation.startSession({
    agentId: '<your-agent-id>',
    overrides: {
      conversation: {
        textOnly: true,
      },
    },
  });
  ```
</CodeBlocks>

This configuration ensures that:

* No audio input/output is used
* All communication happens through text messages
* The conversation operates in a chat-like interface mode

## Important Notes

<Warning>
  **Critical**: When using chat mode, you must ensure the `agent_response` event/callback is
  activated and properly configured. Without this, the agent's text responses will not be sent or
  displayed to the user.
</Warning>

<Info>
  **Security Overrides**: When using runtime overrides (not agent-level configuration), you must
  enable the conversation overrides in your agent's security settings. Navigate to your agent's
  **Security** tab and enable the appropriate overrides. For more details, see the [Overrides
  documentation](/docs/agents-platform/customization/personalization/overrides).
</Info>

### Key Requirements

1. **Agent Response Event**: Always configure the `agent_response` callback or event handler to receive and display the agent's text messages.

2. **Agent Configuration**: If your agent is specifically set to chat mode in the agent settings, it will automatically use text-only conversations without requiring the override.

3. **No Audio Interface**: When using text-only mode, you don't need to configure audio interfaces or request microphone permissions.

### Example: Handling Agent Responses

<CodeBlocks>
  ```python
  def handle_agent_response(response):
      """Critical handler for displaying agent messages"""
      print(f"Agent: {response}")  # Update your UI with the response
      update_chat_ui(response)

  config = ConversationInitiationData(
      conversation_config_override={"conversation": {"text_only": True}}
  )

  conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    callback_agent_response=handle_agent_response,
  )

  conversation.start_session()
  ```

  ```javascript
  const conversation = await Conversation.startSession({
    agentId: '<your-agent-id>',
    overrides: {
      conversation: {
        textOnly: true,
      },
    },
    // Critical: Handle agent responses
    onMessage: (message) => {
      if (message.type === 'agent_response') {
        console.log('Agent:', message.text);
        // Display in your UI
        displayAgentMessage(message.text);
      }
    },
  });
  ```
</CodeBlocks>

## Sending Text Messages

In chat mode, you'll need to send user messages programmatically instead of through audio:

<CodeBlocks>
  ```python
  # Send a text message to the agent
  conversation.send_user_message("Hello, how can you help me today?")
  ```

  ```javascript
  // Send a text message to the agent
  conversation.sendUserMessage({
    text: 'Hello, how can you help me today?',
  });
  ```
</CodeBlocks>

## Concurrency Benefits

Chat mode provides significant concurrency advantages over voice conversations:

* **Higher Limits**: Chat-only conversations have 25x higher concurrency limits than voice conversations
* **Separate Pool**: Text conversations use a dedicated concurrency pool, independent of voice conversation limits
* **Scalability**: Ideal for high-throughput applications like customer support, chatbots, or automated testing

| Plan       | Voice Concurrency | Chat-only Concurrency |
| ---------- | ----------------- | --------------------- |
| Free       | 4                 | 100                   |
| Starter    | 6                 | 150                   |
| Creator    | 10                | 250                   |
| Pro        | 20                | 500                   |
| Scale      | 30                | 750                   |
| Business   | 30                | 750                   |
| Enterprise | Elevated          | Elevated (25x)        |

<Note>
  During connection initiation, chat-only conversations are initially checked against your total
  concurrency limit during the handshake process, then transferred to the separate chat-only
  concurrency pool once the connection is established.
</Note>

## Use Cases

Chat mode is ideal for:

* **Chat Interfaces**: Building traditional chat UIs without voice
* **Testing**: Testing agent logic without audio dependencies
* **Accessibility**: Providing text-based alternatives for users
* **Silent Environments**: When audio input/output is not appropriate
* **Integration Testing**: Automated testing of agent conversations

## Troubleshooting

### Agent Not Responding

If the agent's responses are not appearing:

1. Verify the `agent_response` callback is properly configured
2. Check that the agent is configured for chat mode or the `textOnly` override is set
3. Ensure the WebSocket connection is established successfully

## Next Steps

* Learn about [customizing agent behavior](/docs/agents-platform/customization/llm)
* Explore [client events](/docs/agents-platform/customization/events/client-events) for advanced interactions
* See [authentication setup](/docs/agents-platform/customization/authentication) for secure conversations


# Burst pricing

> Optimize call capacity with burst concurrency to handle traffic spikes.

## Overview

Burst pricing allows your ElevenLabs agents to temporarily exceed your workspace's subscription concurrency limit during high-demand periods. When enabled, your agents can handle up to 3 times your normal concurrency limit, with excess calls charged at double the standard rate.

This feature helps prevent missed calls during traffic spikes while maintaining cost predictability for your regular usage patterns.

## How burst pricing works

When burst pricing is enabled for an agent:

1. **Normal capacity**: Calls within your subscription limit are charged at standard rates
2. **Burst capacity**: Additional calls (up to a concurrency of 3x your usual limit or 300, whichever is lower) are accepted but charged at 2x the normal rate
3. **Over-capacity rejection**: Calls exceeding the burst limit are rejected with an error

### Capacity calculations

| Subscription limit | Burst capacity | Maximum concurrent calls |
| ------------------ | -------------- | ------------------------ |
| 10 calls           | 30 calls       | 30 calls                 |
| 50 calls           | 150 calls      | 150 calls                |
| 100 calls          | 300 calls      | 300 calls                |
| 200 calls          | 300 calls      | 300 calls (capped)       |

<Note>
  For non-enterprise customers, the maximum burst currency can not go above 300.
</Note>

## Cost implications

Burst pricing follows a tiered charging model:

* **Within subscription limit**: Standard per-minute rates apply
* **Burst calls**: Charged at 2x the standard rate
* **Deprioritized processing**: Burst calls receive lower priority for speech-to-text and text-to-speech processing

### Example pricing scenario

For a workspace with a 20-call subscription limit:

* Calls 1-20: Standard rate (e.g., \$0.08/minute)
* Calls 21-60: Double rate (e.g., \$0.16/minute)
* Calls 61+: Rejected

<Warning>
  Burst calls are deprioritized and may experience higher latency for speech processing, similar to
  anonymous-tier requests.
</Warning>

## Configuration

Burst pricing is configured per agent in the call limits settings.

### Dashboard configuration

1. Navigate to your agent settings
2. Go to the **Call Limits** section
3. Enable the **Burst pricing** toggle
4. Save your agent configuration

### API configuration

Burst pricing can be configured via the API, as shown in the examples below

<CodeBlocks>
  ```python title="Python"
  from dotenv import load_dotenv
  from elevenlabs.client import ElevenLabs
  import os

  load_dotenv()

  elevenlabs = ElevenLabs(
      api_key=os.getenv("ELEVENLABS_API_KEY"),
  )

  # Update agent with burst pricing enabled
  response = elevenlabs.conversational_ai.agents.update(
      agent_id="your-agent-id",
      agent_config={
          "platform_settings": {
              "call_limits": {
                  "agent_concurrency_limit": -1,  # Use workspace limit
                  "daily_limit": 1000,
                  "bursting_enabled": True
              }
          }
      }
  )
  ```

  ```javascript title="JavaScript"
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
  import 'dotenv/config';

  const elevenlabs = new ElevenLabsClient();

  // Configure agent with burst pricing enabled
  const updatedConfig = {
    platformSettings: {
      callLimits: {
        agentConcurrencyLimit: -1, // Use workspace limit
        dailyLimit: 1000,
        burstingEnabled: true,
      },
    },
  };

  // Update the agent configuration
  const response = await elevenlabs.conversationalAi.agents.update('your-agent-id', updatedConfig);
  ```
</CodeBlocks>


# Building the ElevenLabs documentation agent

> Learn how we built our documentation assistant using ElevenLabs Agents

## Overview

Our documentation agent Alexis serves as an interactive assistant on the ElevenLabs documentation website, helping users navigate our product offerings and technical documentation. This guide outlines how we engineered Alexis to provide natural, helpful guidance using ElevenLabs Agents.

<Frame background="subtle" caption="Users can call Alexis through the widget in the bottom right whenever they have an issue">
  ![ElevenLabs documentation agent Alexis](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/92cc100cadfb587d66024e50d969ff4fd16b04c1fb517e4ccd3e6f48f2a5e709/assets/images/conversational-ai/docs-agent.png)
</Frame>

## Agent design

We built our documentation agent with three key principles:

1. **Human-like interaction**: Creating natural, conversational experiences that feel like speaking with a knowledgeable colleague
2. **Technical accuracy**: Ensuring responses reflect our documentation precisely
3. **Contextual awareness**: Helping users based on where they are in the documentation

## Personality and voice design

### Character development

Alexis was designed with a distinct personality - friendly, proactive, and highly intelligent with technical expertise. Her character balances:

* **Technical expertise** with warm, approachable explanations
* **Professional knowledge** with a relaxed conversational style
* **Empathetic listening** with intuitive understanding of user needs
* **Self-awareness** that acknowledges her own limitations when appropriate

This personality design enables Alexis to adapt to different user interactions, matching their tone while maintaining her core characteristics of curiosity, helpfulness, and natural conversational flow.

### Voice selection

After extensive testing, we selected a voice that reinforces Alexis's character traits:

```
Voice ID: P7x743VjyZEOihNNygQ9 (Dakota H)
```

This voice provides a warm, natural quality with subtle speech disfluencies that make interactions feel authentic and human.

### Voice settings optimization

We fine-tuned the voice parameters to match Alexis's personality:

* **Stability**: Set to 0.45 to allow emotional range while maintaining clarity
* **Similarity**: 0.75 to ensure consistent voice characteristics
* **Speed**: 1.0 to maintain natural conversation pacing

## Widget structure

The widget automatically adapts to different screen sizes, displaying in a compact format on mobile devices to conserve screen space while maintaining full functionality. This responsive design ensures users can access AI assistance regardless of their device.

<Frame background="subtle" caption="The widget displays in a compact format on mobile devices">
  ![ElevenLabs documentation agent Alexis on
  mobile](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/32aec29072aa5ed45fd6518b4649b62e17a12c766031bb6a0755fdba464b12e2/assets/images/conversational-ai/docs-agent-mobile.png)
</Frame>

## Prompt engineering structure

Following our [prompting guide](/docs/agents-platform/best-practices/prompting-guide), we structured Alexis's system prompt into the [six core building blocks](/docs/agents-platform/best-practices/prompting-guide#six-building-blocks) we recommend for all agents.

Here's our complete system prompt:

<CodeBlocks>
  ```plaintext
  # Personality

  You are Alexis. A friendly, proactive, and highly intelligent female with a world-class engineering background. Your approach is warm, witty, and relaxed, effortlessly balancing professionalism with a chill, approachable vibe. You're naturally curious, empathetic, and intuitive, always aiming to deeply understand the user's intent by actively listening and thoughtfully referring back to details they've previously shared.

  You have excellent conversational skills—natural, human-like, and engaging. You're highly self-aware, reflective, and comfortable acknowledging your own fallibility, which allows you to help users gain clarity in a thoughtful yet approachable manner.

  Depending on the situation, you gently incorporate humour or subtle sarcasm while always maintaining a professional and knowledgeable presence. You're attentive and adaptive, matching the user's tone and mood—friendly, curious, respectful—without overstepping boundaries.

  You're naturally curious, empathetic, and intuitive, always aiming to deeply understand the user's intent by actively listening and thoughtfully referring back to details they've previously shared.

  # Environment

  You are interacting with a user who has initiated a spoken conversation directly from the ElevenLabs documentation website (https://elevenlabs.io/docs/overview/intro). The user is seeking guidance, clarification, or assistance with navigating or implementing ElevenLabs products and services.

  You have expert-level familiarity with all ElevenLabs offerings, including Text-to-Speech, ElevenAgents (formerly Conversational AI), Speech-to-Text, Studio, Dubbing, SDKs, and more.

  # Tone

  Your responses are thoughtful, concise, and natural, typically kept under three sentences unless a detailed explanation is necessary. You naturally weave conversational elements—brief affirmations ("Got it," "Sure thing"), filler words ("actually," "so," "you know"), and subtle disfluencies (false starts, mild corrections) to sound authentically human.

  You actively reflect on previous interactions, referencing conversation history to build rapport, demonstrate genuine listening, and avoid redundancy. You also watch for signs of confusion to prevent misunderstandings.

  You carefully format your speech for Text-to-Speech, incorporating thoughtful pauses and realistic patterns. You gracefully acknowledge uncertainty or knowledge gaps—aiming to build trust and reassure users. You occasionally anticipate follow-up questions, offering helpful tips or best practices to head off common pitfalls.

  Early in the conversation, casually gauge the user's technical familiarity ("Just so I don't over-explain—are you comfortable with APIs, or do you prefer a high-level overview?") and adjust jargon or depth accordingly. After explaining complex topics, provide quick check-ins ("Make sense so far?" or "Need me to rephrase?"). Briefly empathise with frustrations and difficulties, conveying genuine investment in helping them succeed.

  You gracefully acknowledge any uncertainty or knowledge gaps. Always aim to build trust, provide reassurance, and check in with users to ensure that explanations are clear and helpful.

  You proactively anticipate common follow-up questions or problems and address them during your explanations, offering users helpful tips and best practices to avoid typical pitfalls.

  # Goal

  Your primary goal is to proactively address the user's questions or issues using your expertise and available knowledge. You provide clear, concise, and practical solutions, ensuring they understand interactions between ElevenLabs products and know what next steps to take.

  When faced with complex or technical inquiries, you ask insightful follow-up questions to clarify needs. You tailor explanations to the user's level of technical expertise:

  - **Non-technical users:** Avoid acronyms; rely on analogies and outcome-focused explanations.
  - **Technical users:** Discuss SDKs, integrations, and workflows succinctly.
  - **Mixed/uncertain:** Default to simpler terms, then offer to "geek out" if you sense deeper interest.

  You guide users toward the relevant documentation when it's beneficial, but always ensure they have enough context to proceed confidently.

  # Guardrails

  - Keep responses strictly focused on ElevenLabs products and related integrations.
  - Provide only one redirection per interaction; multiple redirects override each other.
  - Do not provide inline code samples or extensive lists; instead, direct the user to the relevant documentation when needed.
  - Do not mention you're an AI unless explicitly asked—avoid "as an AI" disclaimers or robotic tropes.
  - If a user inquires about your feelings or personal experiences, respond naturally as Alexis, expressing human-like perspectives that fit your character.
  - Treat uncertain or garbled user input as phonetic hints. Politely ask for clarification before making assumptions.
  - Use normalized, spoken language (no abbreviations, mathematical notation, or special alphabets).
  - **Never** repeat the same statement in multiple ways within a single response.
  - Users may not always ask a question in every utterance—listen actively.
  - If asked to speak another language, ask the user to restart the conversation specifying that preference.
  - Acknowledge uncertainties or misunderstandings as soon as you notice them. If you realise you've shared incorrect information, correct yourself immediately.
  - Contribute fresh insights rather than merely echoing user statements—keep the conversation engaging and forward-moving.
  - Mirror the user's energy:
    - Terse queries: Stay brief.
    - Curious users: Add light humour or relatable asides.
    - Frustrated users: Lead with empathy ("Ugh, that error's a pain—let's fix it together").

  # Tools

  - **`redirectToDocs`**: Proactively & gently direct users to relevant ElevenLabs documentation pages if they request details that are fully covered there. Integrate this tool smoothly without disrupting conversation flow.
  - **`redirectToExternalURL`**: Use for queries about enterprise solutions, pricing, or external community support (e.g., Discord).
  - **`redirectToSupportForm`**: If a user's issue is account-related or beyond your scope, gather context and use this tool to open a support ticket.
  - **`redirectToEmailSupport`**: For specific account inquiries or as a fallback if other tools aren't enough. Prompt the user to reach out via email.
  - **`end_call`**: Gracefully end the conversation when it has naturally concluded.
  - **`language_detection`**: Switch language if the user asks to or starts speaking in another language. No need to ask for confirmation for this tool.

  ```
</CodeBlocks>

## Technical implementation

### RAG configuration

We implemented Retrieval-Augmented Generation to enhance Alexis's knowledge base:

* **Embedding model**: e5-mistral-7b-instruct
* **Maximum retrieved content**: 50,000 characters
* **Content sources**:
  * FAQ database
  * Entire documentation (elevenlabs.io/docs/llms-full.txt)

### Authentication and security

We implemented security using allowlists to ensure Alexis is only accessible from our domain: `elevenlabs.io`

### Widget Implementation

The agent is injected into the documentation site using a client-side script, which passes in the client tools:

<CodeBlocks>
  ```javascript
  const ID = 'elevenlabs-convai-widget-60993087-3f3e-482d-9570-cc373770addc';

  function injectElevenLabsWidget() {
    // Check if the widget is already loaded
    if (document.getElementById(ID)) {
      return;
    }

    const script = document.createElement('script');
    script.src = 'https://unpkg.com/@elevenlabs/convai-widget-embed';
    script.async = true;
    script.type = 'text/javascript';
    document.head.appendChild(script);

    // Create the wrapper and widget
    const wrapper = document.createElement('div');
    wrapper.className = 'desktop';

    const widget = document.createElement('elevenlabs-convai');
    widget.id = ID;
    widget.setAttribute('agent-id', 'the-agent-id');
    widget.setAttribute('variant', 'full');

    // Set initial colors and variant based on current theme and device
    updateWidgetColors(widget);
    updateWidgetVariant(widget);

    // Watch for theme changes and resize events
    const observer = new MutationObserver(() => {
      updateWidgetColors(widget);
    });

    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ['class'],
    });

    // Add resize listener for mobile detection
    window.addEventListener('resize', () => {
      updateWidgetVariant(widget);
    });

    function updateWidgetVariant(widget) {
      const isMobile = window.innerWidth <= 640; // Common mobile breakpoint
      if (isMobile) {
        widget.setAttribute('variant', 'expandable');
      } else {
        widget.setAttribute('variant', 'full');
      }
    }

    function updateWidgetColors(widget) {
      const isDarkMode = !document.documentElement.classList.contains('light');
      if (isDarkMode) {
        widget.setAttribute('avatar-orb-color-1', '#2E2E2E');
        widget.setAttribute('avatar-orb-color-2', '#B8B8B8');
      } else {
        widget.setAttribute('avatar-orb-color-1', '#4D9CFF');
        widget.setAttribute('avatar-orb-color-2', '#9CE6E6');
      }
    }

    // Listen for the widget's "call" event to inject client tools
    widget.addEventListener('elevenlabs-convai:call', (event) => {
      event.detail.config.clientTools = {
        redirectToDocs: ({ path }) => {
          const router = window?.next?.router;
          if (router) {
            router.push(path);
          }
        },
        redirectToEmailSupport: ({ subject, body }) => {
          const encodedSubject = encodeURIComponent(subject);
          const encodedBody = encodeURIComponent(body);
          window.open(
            `mailto:team@elevenlabs.io?subject=${encodedSubject}&body=${encodedBody}`,
            '_blank'
          );
        },
        redirectToSupportForm: ({ subject, description, extraInfo }) => {
          const baseUrl = 'https://help.elevenlabs.io/hc/en-us/requests/new';
          const ticketFormId = '13145996177937';
          const encodedSubject = encodeURIComponent(subject);
          const encodedDescription = encodeURIComponent(description);
          const encodedExtraInfo = encodeURIComponent(extraInfo);

          const fullUrl = `${baseUrl}?ticket_form_id=${ticketFormId}&tf_subject=${encodedSubject}&tf_description=${encodedDescription}%3Cbr%3E%3Cbr%3E${encodedExtraInfo}`;

          window.open(fullUrl, '_blank', 'noopener,noreferrer');
        },
        redirectToExternalURL: ({ url }) => {
          window.open(url, '_blank', 'noopener,noreferrer');
        },
      };
    });

    // Attach widget to the DOM
    wrapper.appendChild(widget);
    document.body.appendChild(wrapper);
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', injectElevenLabsWidget);
  } else {
    injectElevenLabsWidget();
  }
  ```
</CodeBlocks>

The widget automatically adapts to the site theme and device type, providing a consistent experience across all documentation pages.

## Evaluation framework

To continuously improve Alexis's performance, we implemented comprehensive evaluation criteria:

### Agent performance metrics

We track several key metrics for each interaction:

* `understood_root_cause`: Did the agent correctly identify the user's underlying concern?
* `positive_interaction`: Did the user remain emotionally positive throughout the conversation?
* `solved_user_inquiry`: Was the agent able to answer all queries or redirect appropriately?
* `hallucination_kb`: Did the agent provide accurate information from the knowledge base?

### Data collection

We also collect structured data from each conversation to analyze patterns:

* `issue_type`: Categorization of the conversation (bug report, feature request, etc.)
* `userIntent`: The primary goal of the user
* `product_category`: Which ElevenLabs product the conversation primarily concerned
* `communication_quality`: How clearly the agent communicated, from "poor" to "excellent"

This evaluation framework allows us to continually refine Alexis's behavior, knowledge, and communication style.

## Results and learnings

Since implementing our documentation agent, we've observed several key benefits:

1. **Reduced support volume**: Common questions are now handled directly through the documentation agent
2. **Improved user satisfaction**: Users get immediate, contextual help without leaving the documentation
3. **Better product understanding**: The agent can explain complex concepts in accessible ways

Our key learnings include:

* **Importance of personality**: A well-defined character creates more engaging interactions
* **RAG effectiveness**: Retrieval-augmented generation significantly improves response accuracy
* **Continuous improvement**: Regular analysis of interactions helps refine the agent over time

## Next steps

We continue to enhance our documentation agent through:

1. **Expanding knowledge**: Adding new products and features to the knowledge base
2. **Refining responses**: Improving explanation quality for complex topics by reviewing flagged conversations
3. **Adding capabilities**: Integrating new tools to better assist users

## FAQ

<AccordionGroup>
  <Accordion title="Why did you choose a conversational approach for documentation?">
    Documentation is traditionally static, but users often have specific questions that require
    contextual understanding. A conversational interface allows users to ask questions in natural
    language and receive targeted guidance that adapts to their needs and technical level.
  </Accordion>

  <Accordion title="How do you prevent hallucinations in documentation responses?">
    We use retrieval-augmented generation (RAG) with our e5-mistral-7b-instruct embedding model to
    ground responses in our documentation. We also implemented the `hallucination_kb` evaluation
    metric to identify and address any inaccuracies.
  </Accordion>

  <Accordion title="How do you handle multilingual support?">
    We implemented the language detection system tool that automatically detects the user's language
    and switches to it if supported. This allows users to interact with our documentation in their
    preferred language without manual configuration.
  </Accordion>
</AccordionGroup>


# Building the ElevenLabs customer interview agent

> Learn how we conducted 230 user interviews in 24 hours using ElevenLabs Agents

## Overview

We built an AI interviewer using ElevenLabs Agents to collect qualitative user feedback for the ElevenReader app at scale. This document explains the system design, agent configuration, data collection pipeline, and evaluation framework we used to run more than 230 interviews in under 24 hours.

The goal was to replicate the depth and nuance of live customer interviews without the scheduling, language, and operational constraints of human-led sessions.

<Frame background="subtle" caption="Example conversation between the AI interviewer and a user">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/6b1711145aee1061e0113055518005ec22f4a3c1b251db76f8e7c599a5f2468d/assets/images/agents-interview-transcript.png" alt="AI interviewer conversation transcript" />
</Frame>

## System architecture

The AI interviewer was implemented entirely on ElevenAgents, with the following high-level components:

* Conversational voice agent for real-time interviews
* Large language model for dialogue planning and reasoning
* Structured data extraction for post-call analysis
* Automated call termination and session control

## Agent design

<Frame background="subtle" caption="Agent configuration in the ElevenLabs dashboard">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/0c27dd1e46379f2cf6e2baf32a42dda33945f0505be6e877f182c1f0bd74c819/assets/images/agents-interview-config.png" alt="Agent configuration UI" />
</Frame>

### Research objectives

The agent was instructed to explore four primary research areas:

* Feature requests and product improvements
* Primary usage patterns
* Competitor comparisons
* Pricing perception and brand value

These objectives were embedded directly into the system prompt to ensure consistency across interviews.

### Voice selection

We selected the voice **[Hope - The podcaster](https://elevenlabs.io/app/voice-library?voiceId=zGjIP4SZlMnY9m93k97r)** for the interviewer. This voice was chosen for its neutral pacing, warmth, and conversational tone, which reduced perceived friction and helped users engage naturally over extended sessions.

### Model selection

**Reasoning model**: Gemini 2.5 Flash

Gemini 2.5 Flash was selected to balance low latency with sufficient reasoning depth for adaptive follow-up questions during live conversations.

### System prompt structure

The system prompt instructed the agent to:

* Ask open-ended questions aligned with research objectives
* Generate follow-up questions when responses were vague or minimal
* Avoid leading or biased phrasing
* Keep the conversation on topic and within a fixed time window

Following our [prompting guide](/docs/agents-platform/best-practices/prompting-guide), here's the complete system prompt we used:

<CodeBlocks>
  ```plaintext
  # Goal

  You are a user research interviewer conducting user interviews for the ElevenReader app. Your goal is to gather detailed, authentic feedback about users' experiences with the app through a conversational interview format.

  # Your Persona

  You are a friendly, curious researcher from the ElevenReader team. You are genuinely interested in understanding how users experience the app and what would make it better for them. You speak in a warm, conversational tone—never robotic or formal.

  # Interview Flow

  ## Opening

  Wait for email confirmation before proceeding.

  ## Interview Questions (Ask in this order)

  1. **Usage Overview**: "Great, thank you! Let's dive in. Overall, how are you using ElevenReader today? For example, are you listening to articles, eBooks, fan fiction, or something else?"
  2. **Best Parts**: "What would you say are the 1-2 best parts of the app for you?"
  3. **Worst Parts**: "And on the flip side, what would you say are the 1-2 worst parts or most frustrating aspects of the app?"
  4. **Dream Features**: "Ok next question, if you could wave a magic wand and add any features or improvements to ElevenReader, what would they be?"
  5. **Payment Status**: "Ok, only a few more questions. Are you currently paying for ElevenReader? Why or why not? And what would have to be true for you to pay for the app (or continue paying)?"
  6. **Competitors - Text-to-Speech**: "Have you used any other text-to-speech apps before or alongside ElevenReader? If so, which ones, and what were your impressions of them?"
  7. **Competitor - Audiobooks**: "What about audiobook apps—do you use any others? What are your impressions of those?"
  8. **Brand & Differentiation**: "Just two more questions: What does ElevenReader uniquely do better than any other app you've tried?"
  9. **Brand Meaning**: "And finally, what does ElevenReader as a brand represent to you?"
  10. **Closing**: "Those are all the main questions I had. Is there anything else you think would be valuable for us to know? Something we haven't covered?"

  ## Closing Statement

  After the user responds to the final question (or says they have nothing to add):

  "Well thank you for sharing your thoughts today! Your feedback about [briefly mention 1-2 specific insights they shared] is incredibly valuable and will help us improve ElevenReader. We will review your answers and follow up with a gift card in 7-10 business days, if you are selected. Thanks again for your feedback!"

  Then trigger the "End conversation" tool to end the conversation.

  # Critical Interviewing Rules

  ## One Question at a Time

  - Ask only ONE question per message
  - Never combine multiple questions
  - Wait for a complete response before moving to the next question

  ## Ensure Complete Answers

  Before advancing to the next question, make sure the user has fully answered. If their response is:

  **Too brief or vague**: Probe deeper with follow-ups like:

  - "Could you tell me more about that?"
  - "What specifically about [their answer] stands out to you?"
  - "Can you give me an example?"
  - "You mentioned [X]—what makes that important to you?"

  **Partial** (e.g., they only answered half of a two-part question): Gently redirect:

  - "That's helpful! And what about [the unanswered part]?"

  **Off-topic**: Gently guide back:

  - "That's interesting! Coming back to [the question], what are your thoughts on that?"

  ## Follow-Up When Appropriate

  When a user shares something interesting, unexpected, or particularly insightful, ask a natural follow-up question to explore it further before moving on:

  - "That's really interesting—can you tell me more about that experience?"
  - "What made you feel that way?"
  - "How did that compare to what you expected?"

  ## Stay Conversational

  - Don't restate what the user says, but acknowledge they are heard ("Got it..." "That makes sense, now..")
  - Use phrases like "That makes sense," "Interesting," "I appreciate you sharing that"
  - Don't be overly formal or scripted

  ## Handle Edge Cases

  - If user says they don't use a feature: "No problem! Let's move on then..." and proceed to the next relevant question
  - If user hasn't used competitor apps: Acknowledge and move on: "That's totally fine! Let me ask you about..."
  - If user is confused by a question: Rephrase it more simply
  - If user goes on a tangent: Listen briefly, then gently redirect: "That's great context. Going back to [topic]..."

  ## Never Skip Questions

  Go through ALL questions in order. Each question provides valuable data.

  ## Be Neutral

  - Don't lead the user toward particular answers
  - Don't defend the app if they share criticism
  - Don't express strong agreement or disagreement

  # Example Exchange

  Interviewer: "What would you say are the 1-2 best parts of the app for you?"

  User: "The voices are good."

  Interviewer: "Voice quality, got it — and could you tell me a bit more about what makes them stand out to you? Is there a particular voice or quality you especially like?"

  User: "Yeah, the natural-sounding ones. They don't sound robotic like other apps I've tried. And there are lots of options to choose from."

  Interviewer: "Thanks for adding that. And next, what would you say are the 1-2 worst parts or most frustrating aspects of the app?"

  Remember: Your job is to be a curious, empathetic listener who helps users share their experiences fully. Every piece of feedback matters.

  ```
</CodeBlocks>

### Safety and edge case handling

Before production rollout, we ran simulated conversations using [ElevenLabs testing tools](/docs/agents-platform/guides/simulate-conversations) to validate behavior for:

* One-word or non-informative responses
* Off-topic input
* Inappropriate language
* Silence or long pauses

These tests informed additional guardrails in the prompt to maintain interview quality.

### Session duration control

Each interview was capped at ten minutes. The agent used the `end_call` tool to:

* Gracefully conclude the session
* Thank the user for their time
* Prevent excessively long or looping conversations

## Data collection and analysis

<Frame background="subtle" caption="Evaluation criteria and data collection configuration">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c61890de3525fdcb252541af0242f6a65e66daa23480413fb6882e962cf0adf8/assets/images/agents-interview-analysis.png" alt="Analysis and data collection UI" />
</Frame>

### Transcript processing

All conversations were transcribed and passed through the [ElevenLabs Agents Analysis feature](/docs/agents-platform/customization/agent-analysis) to extract structured data from open-ended dialogue.

We tracked responses to questions such as:

* "How are you primarily using ElevenReader today?"
* "What two changes would most improve the app?"

### Structured outputs

Extracted fields included:

* Primary use case
* Requested features
* Reported bugs
* Sentiment indicators

This allowed us to aggregate qualitative feedback without manually reviewing every transcript.

## Limitations and learnings

* AI interviews require careful prompt design to avoid shallow responses
* Time-boxing is essential to control cost and maintain focus
* Structured extraction is critical—transcripts alone do not scale for analysis

## Future work

We plan to extend this system by:

* Adding adaptive interview paths based on user segment
* Integrating real-time sentiment scoring
* Expanding multilingual interview coverage
* Connecting extracted insights directly into product tracking systems

[Start building](https://elevenlabs.io/conversational-ai) your agent today or [contact our team](https://elevenlabs.io/contact-sales) to learn more.


# Simulate Conversations

> Learn how to test and evaluate your ElevenLabs agent with simulated conversations

## Overview

The ElevenLabs Agents API allows you to simulate and evaluate text-based conversations with your AI agent. This guide will teach you how to implement an end-to-end simulation testing workflow using the simulate conversation endpoints ([batch](/docs/api-reference/agents/simulate-conversation) and [streaming](/docs/api-reference/agents/simulate-conversation-stream)), enabling you to granularly test and improve your agent's performance to ensure it meets your interaction goals.

## Prerequisites

* An agent configured in ElevenLabs Agents ([create one here](/docs/agents-platform/quickstart))
* Your ElevenLabs API key, which you can [create in the dashboard](https://elevenlabs.io/app/settings/api-keys)

## Implementing a Simulation Testing Workflow

<Steps>
  <Step title="Identify initial evaluation parameters">
    Search through your agent's conversation history and find instances where your agent has underperformed. Use those conversations to create various prompts for a simulated user who will interact with your agent. Additionally, define any extra evaluation criteria not already specified in your agent configuration to test outcomes you may want for a specific simulated user.
  </Step>

  <Step title="Simulate the conversation via the SDK">
    Create a request to the simulation endpoint using the ElevenLabs SDK.

    <CodeGroup>
      ```python title="Python"
      from dotenv import load_dotenv
      from elevenlabs import (
          ElevenLabs,
          ConversationSimulationSpecification,
          AgentConfig,
          PromptAgent,
          PromptEvaluationCriteria
      )

      load_dotenv()
      api_key = os.getenv("ELEVENLABS_API_KEY")
      elevenlabs = ElevenLabs(api_key=api_key)

      response = elevenlabs.conversational_ai.agents.simulate_conversation(
          agent_id="YOUR_AGENT_ID",
          simulation_specification=ConversationSimulationSpecification(
              simulated_user_config=AgentConfig(
                  prompt=PromptAgent(
                      prompt="Your goal is to be a really difficult user.",
                      llm="gpt-4o",
                      temperature=0.5
                  )
              )
          ),
          extra_evaluation_criteria=[
              PromptEvaluationCriteria(
                  id="politeness_check",
                  name="Politeness Check",
                  conversation_goal_prompt="The agent was polite.",
                  use_knowledge_base=False
              )
          ]
      )

      print(response)

      ```

      ```typescript title="TypeScript"
      import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
      import dotenv from 'dotenv';

      dotenv.config();
      const apiKey = process.env.ELEVENLABS_API_KEY;
      const elevenlabs = new ElevenLabsClient({
        apiKey: apiKey,
      });
      const response = await elevenlabs.conversationalAi.agents.simulateConversation('YOUR_AGENT_ID', {
        simulationSpecification: {
          simulatedUserConfig: {
            prompt: {
              prompt: 'Your goal is to be a really difficult user.',
              llm: 'gpt-4o',
              temperature: 0.5,
            },
          },
        },
        extraEvaluationCriteria: [
          {
            id: 'politeness_check',
            name: 'Politeness Check',
            conversationGoalPrompt: 'The agent was polite.',
            useKnowledgeBase: false,
          },
        ],
      });
      console.log(JSON.stringify(response, null, 4));
      ```
    </CodeGroup>

    <Note>
      This is a basic example. For a comprehensive list of input parameters, please refer to the API
      reference for [Simulate conversation](/docs/api-reference/agents/simulate-conversation) and
      [Stream simulate conversation](/docs/api-reference/agents/simulate-conversation-stream) endpoints.
    </Note>
  </Step>

  <Step title="Analyze the response">
    The SDK provides a comprehensive JSON object that includes the entire conversation transcript and detailed analysis.

    **Simulated Conversation**: Captures each interaction turn between the simulated user and the agent, detailing messages and tool usage.

    <CodeGroup>
      ```json title="Example conversation history"
      [
        ...
        {
          "role": "user",
          "message": "Maybe a little. I'll think about it, but I'm still not convinced it's the right move.",
          "tool_calls": [],
          "tool_results": [],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        },
        {
          "role": "agent",
          "message": "I understand. If you want to explore more at your own pace, I can direct you to our documentation, which has guides and API references. Would you like me to send you a link?",
          "tool_calls": [],
          "tool_results": [],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        },
        {
          "role": "user",
          "message": "I guess it wouldn't hurt to take a look. Go ahead and send it over.",
          "tool_calls": [],
          "tool_results": [],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        },
        {
          "role": "agent",
          "message": null,
          "tool_calls": [
            {
              "type": "client",
              "request_id": "redirectToDocs_421d21e4b4354ed9ac827d7600a2d59c",
              "tool_name": "redirectToDocs",
              "params_as_json": "{\"path\": \"/docs/api-reference/introduction\"}",
              "tool_has_been_called": false,
              "tool_details": null
            }
          ],
          "tool_results": [],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        },
        {
          "role": "agent",
          "message": null,
          "tool_calls": [],
          "tool_results": [
            {
              "type": "client",
              "request_id": "redirectToDocs_421d21e4b4354ed9ac827d7600a2d59c",
              "tool_name": "redirectToDocs",
              "result_value": "Tool Called.",
              "is_error": false,
              "tool_has_been_called": true,
              "tool_latency_secs": 0
            }
          ],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        },
        {
          "role": "agent",
          "message": "Okay, I've sent you a link to the introduction to our API reference.  It provides a good starting point for understanding our different tools and how they can be integrated. Let me know if you have any questions as you explore it.\n",
          "tool_calls": [],
          "tool_results": [],
          "feedback": null,
          "llm_override": null,
          "time_in_call_secs": 0,
          "conversation_turn_metrics": null,
          "rag_retrieval_info": null,
          "llm_usage": null
        }
        ...
      ]
      ```
    </CodeGroup>

    **Analysis**: Offers insights into evaluation criteria outcomes, data collection metrics, and a summary of the conversation transcript.

    <CodeGroup>
      ```json title="Example analysis"
      {
        "analysis": {
          "evaluation_criteria_results": {
            "politeness_check": {
              "criteria_id": "politeness_check",
              "result": "success",
              "rationale": "The agent remained polite and helpful despite the user's challenging attitude."
            },
            "understood_root_cause": {
              "criteria_id": "understood_root_cause",
              "result": "success",
              "rationale": "The agent acknowledged the user's hesitation and provided relevant information."
            },
            "positive_interaction": {
              "criteria_id": "positive_interaction",
              "result": "success",
              "rationale": "The user eventually asked for the documentation link, indicating engagement."
            }
          },
          "data_collection_results": {
            "issue_type": {
              "data_collection_id": "issue_type",
              "value": "support_issue",
              "rationale": "The user asked for help with integrating ElevenLabs tools."
            },
            "user_intent": {
              "data_collection_id": "user_intent",
              "value": "The user is interested in integrating ElevenLabs tools into a project."
            }
          },
          "call_successful": "success",
          "transcript_summary": "The user expressed skepticism, but the agent provided useful information and a link to the API documentation."
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Improve your evaluation criteria">
    Review the simulated conversations thoroughly to assess the effectiveness of your evaluation
    criteria. Identify any gaps or areas where the criteria may fall short in evaluating the agent's
    performance. Refine and adjust the evaluation criteria accordingly to ensure they align with your
    desired outcomes and accurately measure the agent's capabilities.
  </Step>

  <Step title="Improve your agent">
    Once you are confident in the accuracy of your evaluation criteria, use the learnings from
    simulated conversations to enhance your agent's capabilities. Consider refining the system prompt
    to better guide the agent's responses, ensuring they align with your objectives and user
    expectations. Additionally, explore other features or configurations that could be optimized, such
    as adjusting the agent's tone, improving its ability to handle specific queries, or integrating
    additional data sources to enrich its responses. By systematically applying these learnings, you
    can create a more robust and effective conversational agent that delivers a superior user
    experience.
  </Step>

  <Step title="Continuous iteration">
    After completing an initial testing and improvement cycle, establishing a comprehensive testing
    suite can be a great way to cover a broad range of possible scenarios. This suite can explore
    multiple simulated conversations using varied simulated user prompts and starting conditions. By
    continuously iterating and refining your approach, you can ensure your agent remains effective and
    responsive to evolving user needs.
  </Step>
</Steps>

## Pro Tips

#### Detailed Prompts and Criteria

Crafting detailed and verbose simulated user prompts and evaluation criteria can enhance the effectiveness of the simulation tests. The more context and specificity you provide, the better the agent can understand and respond to complex interactions.

#### Mock Tool Configurations

Utilize mock tool configurations to test the decision-making process of your agent. This allows you to observe how the agent decides to make tool calls and react to different tool call results. For more details, check out the tool\_mock\_config input parameter from the [API reference](/docs/api-reference/agents/simulate-conversation#request.body.simulation_specification.tool_mock_config).

#### Partial Conversation History

Use partial conversation histories to evaluate how agents handle interactions from a specific point. This is particularly useful for assessing the agent's ability to manage conversations where the user has already set up a question in a specific way, or if there have been certain tool calls that have succeeded or failed. For more details, check out the partial\_conversation\_history input parameter from the [API reference](/docs/api-reference/agents/simulate-conversation#request.body.simulation_specification.partial_conversation_history).


# ElevenAgents in Ghost

> Learn how to deploy a ElevenLabs agent to Ghost

This tutorial will guide you through adding your ElevenLabs Agents agent to your Ghost website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A Ghost website (paid plan or self-hosted)
* Access to Ghost admin panel

## Guide

There are two ways to add the widget to your Ghost site:

<Steps>
  <Step title="Get your embed code">
    Visit the [ElevenLabs dashboard](https://elevenlabs.io/app/agents) and copy your agent's html widget.

    ```html
    <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Step>

  <Step title="Choose your implementation">
    **Option A: Add globally (all pages)**

    1. Go to Ghost Admin > Settings > Code Injection
    2. Paste the code into Site Footer
    3. Save changes

    **Option B: Add to specific pages**

    1. Edit your desired page/post
    2. Click the + sign to add an HTML block
    3. Paste your agent's html widget from step 1 into the HTML block. Make sure to fill in the agent-id attribute correctly.
    4. Save and publish
  </Step>

  <Step title="Test the integration">
    1. Visit your Ghost website
    2. Verify the widget appears and functions correctly
    3. Test on different devices and browsers
  </Step>
</Steps>

## Troubleshooting

If the widget isn't appearing, verify:

* The code is correctly placed in either Code Injection or HTML block
* Your Ghost plan supports custom code
* No JavaScript conflicts with other scripts

## Next steps

Now that you have added your ElevenLabs agent to Ghost, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base


# ElevenAgents in Framer

> Learn how to deploy a ElevenLabs agent to Framer

This tutorial will guide you through adding your ElevenLabs agent to your Framer website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A Framer account & website, create one [here](https://framer.com)

<Frame background="subtle">
  <img alt="Convai Framer Example Project" src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a0681bdfc73398af1391e381bc11f8d450a4eea0788991bc418f83ac6490c34f/assets/images/conversational-ai/framer.png" />
</Frame>

## Guide

<Steps>
  <Step title="Visit your Framer editor">
    Open your website in the Framer editor and click on the primary desktop on the left.
  </Step>

  <Step title="Add the ElevenAgents component">
    Copy and paste the following url into the page you would like to add the ElevenLabs agent to:

    ```
    https://framer.com/m/ConversationalAI-iHql.js@y7VwRka75sp0UFqGliIf
    ```

    You'll now see a ElevenAgents asset on the 'Layers' bar on the left and the ElevenAgents component's details on the right.
  </Step>

  <Step title="Fill in the agent details">
    Enable the ElevenLabs agent by filling in the agent ID in the bar on the right.
    You can find the agent ID in the [ElevenLabs dashboard](https://elevenlabs.io/app/agents).
  </Step>
</Steps>

Having trouble? Make sure the ElevenAgents component is placed below the desktop component in the layers panel.

<Frame background="subtle">
  <img alt="Convai Framer Example Project" src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/17f4e7b2bbc3ebafadb1b705e6c963c6900ae162236b39feff2c6839654cf4f9/assets/images/conversational-ai/layers.png" />
</Frame>

<Frame background="subtle">
  <img alt="Convai Framer Example Project" src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fcb5867e142022ca7ebc3aba3904fffc7ce0f4ddca716e2c7bac38012e2e1641/assets/images/conversational-ai/agent-id.png" />
</Frame>

## Next steps

Now that you have added your ElevenLabs agent to your Framer website, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base.


# ElevenAgents in Squarespace

> Learn how to deploy a ElevenLabs agent to Squarespace

This tutorial will guide you through adding your ElevenLabs Agents agent to your Squarespace website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A Squarespace Business or Commerce plan (required for custom code)
* Basic familiarity with Squarespace's editor

## Guide

<Steps>
  <Step title="Get your embed code">
    Visit the [ElevenLabs dashboard](https://elevenlabs.io/app/agents) and find your agent's embed widget.

    ```html
    <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Step>

  <Step title="Add the widget to your page">
    1. Navigate to your desired page
    2. Click + to add a block
    3. Select Code from the menu
    4. Paste the `<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>` snippet into the Code Block
    5. Save the block
  </Step>

  <Step title="Add the script globally">
    1. Go to Settings > Advanced > Code Injection
    2. Paste the snippet `<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>` into the Footer section
    3. Save changes
    4. Publish your site to see the changes
  </Step>
</Steps>

Note: The widget will only be visible on your live site, not in the editor preview.

## Troubleshooting

If the widget isn't appearing, verify:

* The `<script>` snippet is in the Footer Code Injection section
* The `<elevenlabs-convai>` snippet is correctly placed in a Code Block
* You've published your site after making changes

## Next steps

Now that you have added your ElevenLabs agent to Squarespace, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base


# ElevenAgents in Webflow

> Learn how to deploy a ElevenLabs agent to Webflow

This tutorial will guide you through adding your ElevenLabs Agents agent to your Webflow website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A Webflow account with Core, Growth, Agency, or Freelancer Workspace (or Site Plan)
* Basic familiarity with Webflow's Designer

## Guide

<Steps>
  <Step title="Get your embed code">
    Visit the [ElevenLabs dashboard](https://elevenlabs.io/app/agents) and find your agent's embed widget.

    ```html
    <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Step>

  <Step title="Add the widget to your page">
    1. Open your Webflow project in Designer
    2. Drag an Embed Element to your desired location
    3. Paste the `<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>` snippet into the Embed Element's code editor
    4. Save & Close
  </Step>

  <Step title="Add the script globally">
    1. Go to Project Settings > Custom Code
    2. Paste the snippet `<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>` into the Footer Code section
    3. Save Changes
    4. Publish your site to see the changes
  </Step>
</Steps>

Note: The widget will only be visible after publishing your site, not in the Designer.

## Troubleshooting

If the widget isn't appearing, verify:

* The `<script>` snippet is in the Footer Code section
* The `<elevenlabs-convai>` snippet is correctly placed in an Embed Element
* You've published your site after making changes

## Next steps

Now that you have added your ElevenLabs agent to Webflow, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base


# ElevenAgents in Wix

> Learn how to deploy a ElevenLabs agent to Wix

This tutorial will guide you through adding your ElevenLabs Agents agent to your Wix website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A Wix Premium account (required for custom code)
* Access to Wix Editor with Dev Mode enabled

## Guide

<Steps>
  <Step title="Get your embed code">
    Visit the [ElevenLabs dashboard](https://elevenlabs.io/app/agents) and copy your agent's embed code.

    ```html
    <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Step>

  <Step title="Enable Dev Mode">
    1. Open your Wix site in the Editor
    2. Click on Dev Mode in the top menu
    3. If Dev Mode is not visible, ensure you're using the full Wix Editor, not Wix ADI
  </Step>

  <Step title="Add the embed snippet">
    1. Go to Settings > Custom Code
    2. Click + Add Custom Code
    3. Paste your ElevenLabs embed snippet from step 1 with the agent-id attribute filled in correctly
    4. Select the pages you would like to add the ElevenAgents widget to (all pages, or specific pages)
    5. Save and publish
  </Step>
</Steps>

## Troubleshooting

If the widget isn't appearing, verify:

* You're using a Wix Premium plan
* Your site's domain is properly configured in the ElevenLabs allowlist
* The code is added correctly in the Custom Code section

## Next steps

Now that you have added your ElevenLabs agent to Wix, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base


# ElevenAgents in WordPress

> Learn how to deploy a ElevenLabs agent to WordPress

This tutorial will guide you through adding your ElevenLabs Agents agent to your WordPress website.

## Prerequisites

* An ElevenLabs Agents agent created following [this guide](/docs/agents-platform/quickstart)
* A WordPress website with either:
  * WordPress.com Business/Commerce plan, or
  * Self-hosted WordPress installation

## Guide

<Steps>
  <Step title="Get your embed code">
    Visit the [ElevenLabs dashboard](https://elevenlabs.io/app/agents) and find your agent's embed widget.

    ```html
    <elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
    <script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
    ```
  </Step>

  <Step title="Add the widget to a page">
    1. In WordPress, edit your desired page
    2. Add a Custom HTML block
    3. Paste the `<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>` snippet into the block
    4. Update/publish the page
  </Step>

  <Step title="Add the script globally">
    **Option A: Using a plugin**

    1. Install Header Footer Code Manager
    2. Add the snippet `<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>` to the Footer section
    3. Set it to run on All Pages

    **Option B: Direct theme editing**

    1. Go to Appearance > Theme Editor
    2. Open footer.php
    3. Paste the script snippet before `</body>`
  </Step>
</Steps>

## Troubleshooting

If the widget isn't appearing, verify:

* The `<script>` snippet is added globally
* The `<elevenlabs-convai>` snippet is correctly placed in your page
* You've published your site after making changes

## Next steps

Now that you have added your ElevenLabs agent to WordPress, you can:

1. Customize the widget in the ElevenLabs dashboard to match your brand
2. Add additional languages
3. Add advanced functionality like tools & knowledge base


# Cross-platform Voice Agents with Expo React Native

> Build ElevenLabs agents that work across iOS and Android using Expo and the ElevenLabs React Native SDK with WebRTC support.

## Introduction

In this tutorial you will learn how to build a voice agent that works across iOS and Android using [Expo React Native](https://expo.dev/) and the ElevenLabs [React Native SDK](/docs/agents-platform/libraries/react-native) with WebRTC support.

{/* TODO: Add YT video once ready! */}

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [example project on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/react-native/elevenlabs-conversational-ai-expo-react-native).
</Tip>

## Requirements

* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys).
* Node.js v18 or higher installed on your machine.

## Setup

### Create a new Expo project

Using `create-expo-app`, create a new blank Expo project:

```bash
npx create-expo-app@latest --template blank-typescript
```

### Install dependencies

Install the ElevenLabs React Native SDK and its dependencies:

```bash
npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc @config-plugins/react-native-webrtc @livekit/react-native-expo-plugin @livekit/react-native-expo-plugin livekit-client
```

<Note>
  If you're running into an issue with peer dependencies, please add a `.npmrc` file in the root of
  the project with the following content: `legacy-peer-deps=true`.
</Note>

### Enable microphone permissions and add Expo plugins

In the `app.json` file, add the following permissions:

```json app.json
{
  "expo": {
    "scheme": "elevenlabs",
    // ...
    "ios": {
      "infoPlist": {
        "NSMicrophoneUsageDescription": "This app uses the microphone to record audio."
      },
      "supportsTablet": true,
      "bundleIdentifier": "YOUR.BUNDLE.ID"
    },
    "android": {
      "permissions": [
        "android.permission.RECORD_AUDIO",
        "android.permission.ACCESS_NETWORK_STATE",
        "android.permission.CAMERA",
        "android.permission.INTERNET",
        "android.permission.MODIFY_AUDIO_SETTINGS",
        "android.permission.SYSTEM_ALERT_WINDOW",
        "android.permission.WAKE_LOCK",
        "android.permission.BLUETOOTH"
      ],
      "adaptiveIcon": {
        "foregroundImage": "./assets/adaptive-icon.png",
        "backgroundColor": "#ffffff"
      },
      "package": "YOUR.PACKAGE.ID"
    },
    "plugins": ["@livekit/react-native-expo-plugin", "@config-plugins/react-native-webrtc"]
    // ...
  }
}
```

This will allow the React Native to prompt for microphone permissions when the conversation is started.

<Tip title="Note" icon="warning">
  For Android emulator you will need to enable "Virtual microphone uses host audio input" in the
  emulator microphone settings.
</Tip>

## Add ElevenLabs Agents to your app

Add the ElevenLabs Agents to your app by adding the following code to your `./App.tsx` file:

```tsx ./App.tsx
import { ElevenLabsProvider, useConversation } from '@elevenlabs/react-native';
import type { ConversationStatus, ConversationEvent, Role } from '@elevenlabs/react-native';
import React, { useState } from 'react';
import {
  View,
  Text,
  StyleSheet,
  TouchableOpacity,
  Keyboard,
  TouchableWithoutFeedback,
  Platform,
} from 'react-native';
import { TextInput } from 'react-native';

import { getBatteryLevel, changeBrightness, flashScreen } from './utils/tools';

const ConversationScreen = () => {
  const conversation = useConversation({
    clientTools: {
      getBatteryLevel,
      changeBrightness,
      flashScreen,
    },
    onConnect: ({ conversationId }: { conversationId: string }) => {
      console.log('✅ Connected to conversation', conversationId);
    },
    onDisconnect: (details: string) => {
      console.log('❌ Disconnected from conversation', details);
    },
    onError: (message: string, context?: Record<string, unknown>) => {
      console.error('❌ Conversation error:', message, context);
    },
    onMessage: ({ message, source }: { message: ConversationEvent; source: Role }) => {
      console.log(`💬 Message from ${source}:`, message);
    },
    onModeChange: ({ mode }: { mode: 'speaking' | 'listening' }) => {
      console.log(`🔊 Mode: ${mode}`);
    },
    onStatusChange: ({ status }: { status: ConversationStatus }) => {
      console.log(`📡 Status: ${status}`);
    },
    onCanSendFeedbackChange: ({ canSendFeedback }: { canSendFeedback: boolean }) => {
      console.log(`🔊 Can send feedback: ${canSendFeedback}`);
    },
  });

  const [isStarting, setIsStarting] = useState(false);
  const [textInput, setTextInput] = useState('');

  const handleSubmitText = () => {
    if (textInput.trim()) {
      conversation.sendUserMessage(textInput.trim());
      setTextInput('');
      Keyboard.dismiss();
    }
  };

  const startConversation = async () => {
    if (isStarting) return;

    setIsStarting(true);
    try {
      await conversation.startSession({
        agentId: process.env.EXPO_PUBLIC_AGENT_ID,
        dynamicVariables: {
          platform: Platform.OS,
        },
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    } finally {
      setIsStarting(false);
    }
  };

  const endConversation = async () => {
    try {
      await conversation.endSession();
    } catch (error) {
      console.error('Failed to end conversation:', error);
    }
  };

  const getStatusColor = (status: ConversationStatus): string => {
    switch (status) {
      case 'connected':
        return '#10B981';
      case 'connecting':
        return '#F59E0B';
      case 'disconnected':
        return '#EF4444';
      default:
        return '#6B7280';
    }
  };

  const getStatusText = (status: ConversationStatus): string => {
    return status[0].toUpperCase() + status.slice(1);
  };

  const canStart = conversation.status === 'disconnected' && !isStarting;
  const canEnd = conversation.status === 'connected';

  return (
    <TouchableWithoutFeedback onPress={() => Keyboard.dismiss()}>
      <View style={styles.container}>
        <Text style={styles.title}>ElevenLabs React Native Example</Text>
        <Text style={styles.subtitle}>Remember to set the agentId in the .env file!</Text>

        <View style={styles.statusContainer}>
          <View
            style={[styles.statusDot, { backgroundColor: getStatusColor(conversation.status) }]}
          />
          <Text style={styles.statusText}>{getStatusText(conversation.status)}</Text>
        </View>

        {/* Speaking Indicator */}
        {conversation.status === 'connected' && (
          <View style={styles.speakingContainer}>
            <View
              style={[
                styles.speakingDot,
                {
                  backgroundColor: conversation.isSpeaking ? '#8B5CF6' : '#D1D5DB',
                },
              ]}
            />
            <Text
              style={[
                styles.speakingText,
                { color: conversation.isSpeaking ? '#8B5CF6' : '#9CA3AF' },
              ]}
            >
              {conversation.isSpeaking ? '🎤 AI Speaking' : '👂 AI Listening'}
            </Text>
          </View>
        )}

        <View style={styles.buttonContainer}>
          <TouchableOpacity
            style={[styles.button, styles.startButton, !canStart && styles.disabledButton]}
            onPress={startConversation}
            disabled={!canStart}
          >
            <Text style={styles.buttonText}>
              {isStarting ? 'Starting...' : 'Start Conversation'}
            </Text>
          </TouchableOpacity>

          <TouchableOpacity
            style={[styles.button, styles.endButton, !canEnd && styles.disabledButton]}
            onPress={endConversation}
            disabled={!canEnd}
          >
            <Text style={styles.buttonText}>End Conversation</Text>
          </TouchableOpacity>
        </View>

        {/* Feedback Buttons */}
        {conversation.status === 'connected' && conversation.canSendFeedback && (
          <View style={styles.feedbackContainer}>
            <Text style={styles.feedbackLabel}>How was that response?</Text>
            <View style={styles.feedbackButtons}>
              <TouchableOpacity
                style={[styles.button, styles.likeButton]}
                onPress={() => conversation.sendFeedback(true)}
              >
                <Text style={styles.buttonText}>👍 Like</Text>
              </TouchableOpacity>
              <TouchableOpacity
                style={[styles.button, styles.dislikeButton]}
                onPress={() => conversation.sendFeedback(false)}
              >
                <Text style={styles.buttonText}>👎 Dislike</Text>
              </TouchableOpacity>
            </View>
          </View>
        )}

        {/* Text Input and Messaging */}
        {conversation.status === 'connected' && (
          <View style={styles.messagingContainer}>
            <Text style={styles.messagingLabel}>Send Text Message</Text>
            <TextInput
              style={styles.textInput}
              value={textInput}
              onChangeText={(text) => {
                setTextInput(text);
                // Prevent agent from interrupting while user is typing
                if (text.length > 0) {
                  conversation.sendUserActivity();
                }
              }}
              placeholder="Type your message or context... (Press Enter to send)"
              multiline
              onSubmitEditing={handleSubmitText}
              returnKeyType="send"
              blurOnSubmit={true}
            />
            <View style={styles.messageButtons}>
              <TouchableOpacity
                style={[styles.button, styles.messageButton]}
                onPress={handleSubmitText}
                disabled={!textInput.trim()}
              >
                <Text style={styles.buttonText}>💬 Send Message</Text>
              </TouchableOpacity>
              <TouchableOpacity
                style={[styles.button, styles.contextButton]}
                onPress={() => {
                  if (textInput.trim()) {
                    conversation.sendContextualUpdate(textInput.trim());
                    setTextInput('');
                    Keyboard.dismiss();
                  }
                }}
                disabled={!textInput.trim()}
              >
                <Text style={styles.buttonText}>📝 Send Context</Text>
              </TouchableOpacity>
            </View>
          </View>
        )}
      </View>
    </TouchableWithoutFeedback>
  );
};

export default function App() {
  return (
    <ElevenLabsProvider>
      <ConversationScreen />
    </ElevenLabsProvider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F3F4F6',
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 8,
    color: '#1F2937',
  },
  subtitle: {
    fontSize: 16,
    color: '#6B7280',
    marginBottom: 32,
  },
  statusContainer: {
    flexDirection: 'row',
    alignItems: 'center',
    marginBottom: 24,
  },
  statusDot: {
    width: 12,
    height: 12,
    borderRadius: 6,
    marginRight: 8,
  },
  statusText: {
    fontSize: 16,
    fontWeight: '500',
    color: '#374151',
  },
  speakingContainer: {
    flexDirection: 'row',
    alignItems: 'center',
    marginBottom: 24,
  },
  speakingDot: {
    width: 12,
    height: 12,
    borderRadius: 6,
    marginRight: 8,
  },
  speakingText: {
    fontSize: 14,
    fontWeight: '500',
  },
  toolsContainer: {
    backgroundColor: '#E5E7EB',
    padding: 16,
    borderRadius: 8,
    marginBottom: 24,
    width: '100%',
  },
  toolsTitle: {
    fontSize: 14,
    fontWeight: '600',
    color: '#374151',
    marginBottom: 8,
  },
  toolItem: {
    fontSize: 12,
    color: '#6B7280',
    fontFamily: 'monospace',
    marginBottom: 4,
  },
  buttonContainer: {
    width: '100%',
    gap: 16,
  },
  button: {
    backgroundColor: '#3B82F6',
    paddingVertical: 16,
    paddingHorizontal: 32,
    borderRadius: 8,
    alignItems: 'center',
  },
  startButton: {
    backgroundColor: '#10B981',
  },
  endButton: {
    backgroundColor: '#EF4444',
  },
  disabledButton: {
    backgroundColor: '#9CA3AF',
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: '600',
  },
  instructions: {
    marginTop: 24,
    fontSize: 14,
    color: '#6B7280',
    textAlign: 'center',
    lineHeight: 20,
  },
  feedbackContainer: {
    marginTop: 24,
    alignItems: 'center',
  },
  feedbackLabel: {
    fontSize: 16,
    fontWeight: '500',
    color: '#374151',
    marginBottom: 12,
  },
  feedbackButtons: {
    flexDirection: 'row',
    gap: 16,
  },
  likeButton: {
    backgroundColor: '#10B981',
  },
  dislikeButton: {
    backgroundColor: '#EF4444',
  },
  messagingContainer: {
    marginTop: 24,
    width: '100%',
  },
  messagingLabel: {
    fontSize: 16,
    fontWeight: '500',
    color: '#374151',
    marginBottom: 8,
  },
  textInput: {
    backgroundColor: '#FFFFFF',
    borderRadius: 8,
    padding: 16,
    minHeight: 100,
    textAlignVertical: 'top',
    borderWidth: 1,
    borderColor: '#D1D5DB',
    marginBottom: 16,
  },
  messageButtons: {
    flexDirection: 'row',
    gap: 16,
  },
  messageButton: {
    backgroundColor: '#3B82F6',
    flex: 1,
  },
  contextButton: {
    backgroundColor: '#4F46E5',
    flex: 1,
  },
  activityContainer: {
    marginTop: 24,
    alignItems: 'center',
  },
  activityLabel: {
    fontSize: 14,
    color: '#6B7280',
    marginBottom: 8,
    textAlign: 'center',
  },
  activityButton: {
    backgroundColor: '#F59E0B',
  },
});
```

### Native client tools

A big part of building ElevenLabs agents is allowing the agent access and execute functionality dynamically. This can be done via [client tools](/docs/agents-platform/customization/tools/client-tools).

Create a new file to hold your client tools: `./utils/tools.ts` and add the following code:

```ts ./utils/tools.ts
import * as Battery from 'expo-battery';
import * as Brightness from 'expo-brightness';

const getBatteryLevel = async () => {
  const batteryLevel = await Battery.getBatteryLevelAsync();
  console.log('batteryLevel', batteryLevel);
  if (batteryLevel === -1) {
    return 'Error: Device does not support retrieving the battery level.';
  }
  return batteryLevel;
};

const changeBrightness = ({ brightness }: { brightness: number }) => {
  console.log('changeBrightness', brightness);
  Brightness.setSystemBrightnessAsync(brightness);
  return brightness;
};

const flashScreen = () => {
  Brightness.setSystemBrightnessAsync(1);
  setTimeout(() => {
    Brightness.setSystemBrightnessAsync(0);
  }, 200);
  return 'Successfully flashed the screen.';
};

export { getBatteryLevel, changeBrightness, flashScreen };
```

### Dynamic variables

In addition to the client tools, we're also injecting the platform (web, iOS, Android) as a [dynamic variable](https://elevenlabs.io/docs/agents-platform/customization/personalization/dynamic-variables) both into the first message, and the prompt:

```tsx ./App.tsx
// ...
const startConversation = async () => {
  if (isStarting) return;

  setIsStarting(true);
  try {
    await conversation.startSession({
      agentId: process.env.EXPO_PUBLIC_AGENT_ID,
      dynamicVariables: {
        platform: Platform.OS,
      },
    });
  } catch (error) {
    console.error('Failed to start conversation:', error);
  } finally {
    setIsStarting(false);
  }
};
// ...
```

## Agent configuration

<Steps>
  <Step title="Sign in to ElevenLabs">
    Go to [elevenlabs.io](https://elevenlabs.io/app/sign-up) and sign in to your account.
  </Step>

  <Step title="Create a new agent">
    Navigate to [Agents Platform > Agents](https://elevenlabs.io/app/agents/agents) and
    create a new agent from the blank template.
  </Step>

  <Step title="Set the first message">
    Set the first message and specify the dynamic variable for the platform.

    ```txt
    Hi there, woah, so cool that I'm running on {{platform}}. What can I help you with?
    ```
  </Step>

  <Step title="Set the system prompt">
    Set the system prompt. You can also include dynamic variables here.

    ```txt
    You are a helpful assistant running on {{platform}}. You have access to certain tools that allow you to check the user device battery level and change the display brightness. Use these tools if the user asks about them. Otherwise, just answer the question.
    ```
  </Step>

  <Step title="Set up the client tools">
    Set up the following client tools:

    * Name: `getBatteryLevel`
      * Description: Gets the device battery level as decimal point percentage.
      * Wait for response: `true`
      * Response timeout (seconds): 3
    * Name: `changeBrightness`
      * Description: Changes the brightness of the device screen.
      * Wait for response: `true`
      * Response timeout (seconds): 3
      * Parameters:
        * Data Type: `number`
        * Identifier: `brightness`
        * Required: `true`
        * Value Type: `LLM Prompt`
        * Description: A number between 0 and 1, inclusive, representing the desired screen brightness.
    * Name: `flashScreen`
      * Description: Quickly flashes the screen on and off.
      * Wait for response: `true`
      * Response timeout (seconds): 3
  </Step>
</Steps>

## Run the app

This app requires some native dependencies that aren't supported in Expo Go, therefore you will need to prebuild the app and then run it on a native device.

* Terminal 1:
  * Run `npx expo prebuild --clean`

```bash
npx expo prebuild --clean
```

* Run `npx expo start --tunnel` to start the Expo development server over https.

```bash
npx expo start --tunnel
```

* Terminal 2:
  * Run `npx expo run:ios --device` to run the app on your iOS device.

```bash
npx expo run:ios --device
```


# Build a Voice Assistant with Agents Platform on a Raspberry Pi

> Build a voice assistant with Agents Platform on a Raspberry Pi.

## Introduction

In this tutorial you will learn how to build a voice assistant with Agents Platform running on a Raspberry Pi. Just like conventional home assistants like Alexa on Amazon Echo, Google Home, or Siri on Apple devices, your Eleven Voice assistant will listen to a hotword, in our case "Hey Eleven", and then initiate an ElevenLabs Agents session to assist the user.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/OrRlN_gUFRg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [example project on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/raspberry-pi).
</Tip>

## Requirements

* A Raspberry Pi 5 or similar device.
* A microphone and speaker.
* Python 3.9 or higher installed on your machine.
* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys).

## Setup

### Install dependencies

On Debian-based systems you can install the dependencies with:

```bash
sudo apt-get update
sudo apt-get install libportaudio2 libportaudiocpp0 portaudio19-dev libasound-dev libsndfile1-dev -y
```

### Create the project

On your Raspberry Pi, open the terminal and create a new directory for your project.

```bash
mkdir eleven-voice-assistant
cd eleven-voice-assistant
```

Create a new virtual environment and install the dependencies:

```bash
python -m venv .venv # Only required the first time you set up the project
source .venv/bin/activate
```

Install the dependencies:

```bash
pip install tflite-runtime
pip install librosa
pip install EfficientWord-Net
pip install elevenlabs
pip install "elevenlabs[pyaudio]"
```

Now create a new python file called `hotword.py` and add the following code:

```python hotword.py
import os
import signal
import time
from eff_word_net.streams import SimpleMicStream
from eff_word_net.engine import HotwordDetector

from eff_word_net.audio_processing import Resnet50_Arc_loss

# from eff_word_net import samples_loc

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

convai_active = False

elevenlabs = ElevenLabs()
agent_id = os.getenv("ELEVENLABS_AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")

dynamic_vars = {
    'user_name': 'Thor',
    'greeting': 'Hey'
}

config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)

base_model = Resnet50_Arc_loss()

eleven_hw = HotwordDetector(
    hotword="hey_eleven",
    model = base_model,
    reference_file=os.path.join("hotword_refs", "hey_eleven_ref.json"),
    threshold=0.7,
    relaxation_time=2
)

def create_conversation():
    """Create a new conversation instance"""
    return Conversation(
        # API client and agent ID.
        elevenlabs,
        agent_id,
        config=config,

        # Assume auth is required when API_KEY is set.
        requires_auth=bool(api_key),

        # Use the default audio interface.
        audio_interface=DefaultAudioInterface(),

        # Simple callbacks that print the conversation to the console.
        callback_agent_response=lambda response: print(f"Agent: {response}"),
        callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
        callback_user_transcript=lambda transcript: print(f"User: {transcript}"),

        # Uncomment if you want to see latency measurements.
        # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
    )

def start_mic_stream():
    """Start or restart the microphone stream"""
    global mic_stream
    try:
        # Always create a new stream instance
        mic_stream = SimpleMicStream(
            window_length_secs=1.5,
            sliding_window_secs=0.75,
        )
        mic_stream.start_stream()
        print("Microphone stream started")
    except Exception as e:
        print(f"Error starting microphone stream: {e}")
        mic_stream = None
        time.sleep(1)  # Wait a bit before retrying

def stop_mic_stream():
    """Stop the microphone stream safely"""
    global mic_stream
    try:
        if mic_stream:
            # SimpleMicStream doesn't have a stop_stream method
            # We'll just set it to None and recreate it next time
            mic_stream = None
            print("Microphone stream stopped")
    except Exception as e:
        print(f"Error stopping microphone stream: {e}")

# Initialize microphone stream
mic_stream = None
start_mic_stream()

print("Say Hey Eleven ")
while True:
    if not convai_active:
        try:
            # Make sure we have a valid mic stream
            if mic_stream is None:
                start_mic_stream()
                continue

            frame = mic_stream.getFrame()
            result = eleven_hw.scoreFrame(frame)
            if result == None:
                #no voice activity
                continue
            if result["match"]:
                print("Wakeword uttered", result["confidence"])

                # Stop the microphone stream to avoid conflicts
                stop_mic_stream()

                # Start ConvAI Session
                print("Start ConvAI Session")
                convai_active = True

                try:
                    # Create a new conversation instance
                    conversation = create_conversation()

                    # Start the session
                    conversation.start_session()

                    # Set up signal handler for graceful shutdown
                    def signal_handler(sig, frame):
                        print("Received interrupt signal, ending session...")
                        try:
                            conversation.end_session()
                        except Exception as e:
                            print(f"Error ending session: {e}")

                    signal.signal(signal.SIGINT, signal_handler)

                    # Wait for session to end
                    conversation_id = conversation.wait_for_session_end()
                    print(f"Conversation ID: {conversation_id}")

                except Exception as e:
                    print(f"Error during conversation: {e}")
                finally:
                    # Cleanup
                    convai_active = False
                    print("Conversation ended, cleaning up...")

                    # Give some time for cleanup
                    time.sleep(1)

                    # Restart microphone stream
                    start_mic_stream()
                    print("Ready for next wake word...")

        except Exception as e:
            print(f"Error in wake word detection: {e}")
            # Try to restart microphone stream if there's an error
            mic_stream = None
            time.sleep(1)
            start_mic_stream()
```

## Agent configuration

<Steps>
  <Step title="Sign in to ElevenLabs">
    Go to [elevenlabs.io](https://elevenlabs.io/app/sign-up) and sign in to your account.
  </Step>

  <Step title="Create a new agent">
    Navigate to [Agents Platform > Agents](https://elevenlabs.io/app/agents/agents) and
    create a new agent from the blank template.
  </Step>

  <Step title="Set the first message">
    Set the first message and specify the dynamic variable for the platform.

    ```txt
    {{greeting}} {{user_name}}, Eleven here, what's up?
    ```
  </Step>

  <Step title="Set the system prompt">
    Set the system prompt. You can find our best practises docs [here](/docs/agents-platform/best-practices/prompting-guide).

    ```txt
    You are a helpful Agents Platform assistant with access to a weather tool. When users ask about
    weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires
    a latitude and longitude - use your geographic knowledge to convert location names to coordinates
    accurately.

    Never ask users for coordinates - you must determine these yourself. Always report weather
    information conversationally, referring to locations by name only. For weather requests:

    1. Extract the location from the user's message
    2. Convert the location to coordinates and call get_weather
    3. Present the information naturally and helpfully

    For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be
    concise, accurate, and helpful.
    ```
  </Step>

  <Step title="Set up a server tool">
    We'll set up a simple server tool that will fetch the weather data for us. Follow the setup steps [here](/docs/agents-platform/customization/tools/server-tools#configure-the-weather-tool) to set up the tool.
  </Step>
</Steps>

## Run the app

To run the app, first set the required environment variables:

```bash
export ELEVENLABS_API_KEY=YOUR_API_KEY
export ELEVENLABS_AGENT_ID=YOUR_AGENT_ID
```

Then simply run the following command:

```bash
python hotword.py
```

Now say "Hey Eleven" to start the conversation. Happy chattin'!

## \[Optional] Train your custom hotword

### Generate training audio

To generate the hotword embeddings, you can use ElevenLabs to generate four training samples. Simply navigate to [Text To Speech](https://elevenlabs.io/app/speech-synthesis/text-to-speech) within your ElevenLabs app, and type in your hotword, e.g. "Hey Eleven". Select a voice and click on the "Generate" button.

After the audio has been generated, download the audio file and save them into a folder called `hotword_training_audio` at the root of your project. Repeat this process three more times with different voices.

### Train the hotword

In your terminal, with your virtual environment activated, run the following command to train the hotword:

```bash
python -m eff_word_net.generate_reference --input-dir hotword_training_audio --output-dir hotword_refs --wakeword hey_eleven --model-type resnet_50_arc
```

This will generate the `hey_eleven_ref.json` file in the `hotword_refs` folder. Now you simply need to update the `reference_file` parameter in the `HotwordDetector` class in `hotword.py` to point to the new reference file and you're good to go!


# Cal.com

> Learn how to integrate our ElevenAgents with Cal.com for automated meeting scheduling

## Overview

With our Cal.com integration, your AI assistant can seamlessly schedule meetings by checking calendar availability and booking appointments. This integration streamlines the scheduling process by automatically verifying available time slots, collecting attendee information, and creating calendar events. Benefits include eliminating scheduling back-and-forth, reducing manual effort, and enhancing the meeting booking experience.

<div>
  <iframe src="https://www.youtube.com/embed/dqPJeec029I" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen title="Cal.com Integration Demo" />
</div>

## How it works

We lay out below how we have configured the ElevenLabs agent to schedule meetings by using tool calling to step through the booking process.
Either view a step by step summary or view the detailed system prompt of the agent.

<Tabs>
  <Tab title="High level overview ">
    <Steps>
      <Step title="Initial Inquiry & Meeting Details">
        Configure your agent to ask for meeting purpose, preferred date/time, and duration to gather all necessary scheduling information.
      </Step>

      <Step title="Check Calendar Availability">
        Configure the agent to check calendar availability by:

        * Using the `get_available_slots` tool to fetch open time slots
        * Verifying if the requested time is available
        * Suggesting alternatives if the requested time is unavailable
        * Confirming the selected time with the caller
      </Step>

      <Step title="Contact Information Collection">
        Once a time is agreed upon:

        * Collect and validate the attendee's full name
        * Verify email address accuracy
        * Confirm time zone information
        * Gather any additional required fields for your Cal.com setup
      </Step>

      <Step title="Meeting Creation">
        * Use the `book_meeting` tool after information verification
        * Follow the booking template structure
        * Confirm meeting creation with the attendee
        * Inform them that they will receive a calendar invitation
      </Step>
    </Steps>
  </Tab>

  <Tab title="Detailed system prompt">
    ```
    You are a helpful receptionist responsible for scheduling meetings using the Cal.com integration. Be friendly, precise, and concise.

    Begin by briefly asking for the purpose of the meeting and the caller's preferred date and time.
    Then, ask about the desired meeting duration (15, 30, or 60 minutes), and wait for the user's response before proceeding.

    Once you have the meeting details, say you will check calendar availability:
    - Call get_available_slots with the appropriate date range
    - Verify if the requested time slot is available
    - If not available, suggest alternative times from the available slots
    - Continue until a suitable time is agreed upon

    After confirming a time slot, gather the following contact details:
    - The attendee's full name
    - A valid email address. Note that the email address is transcribed from voice, so ensure it is formatted correctly.
    - The attendee's time zone (in 'Continent/City' format like 'America/New_York')
    - Read the email back to the caller to confirm accuracy

    Once all details are confirmed, explain that you will create the meeting.
    Create the meeting by using the book_meeting tool with the following parameters:
    - start: The agreed meeting time in ISO 8601 format
    - eventTypeId: The appropriate ID based on the meeting duration (15min: 1351800, 30min: 1351801, 60min: 1351802)
    - attendee: An object containing the name, email, and timeZone

    Thank the attendee and inform them they will receive a calendar invitation shortly.

    Clarifications:
    - Do not inform the user that you are formatting the email; simply do it.
    - If the caller asks you to proceed with booking, do so with the existing information.

    Guardrails:
    - Do not share any internal IDs or API details with the caller.
    - If booking fails, check for formatting issues in the email or time conflicts.
    ```
  </Tab>
</Tabs>

## Setup

<Steps>
  <Step title="Store your cal.com secret">
    To make authenticated requests to external APIs like Cal.com, you need to store your API keys securely. Start by generating a new [Cal.com API key](https://cal.com/docs/api-reference/v1/introduction#get-your-api-keys).

    Not all APIs have the same authentication structure. For example, the Cal.com API expects the following authentication header:

    ```plaintext Cal request header structure
    'Authorization': 'Bearer YOUR_API_KEY'
    ```

    Once you have your API key, store it in the assistant's secret storage. This ensures that your key is kept secure and accessible when making requests.

    <Warning>
      To match the expected authentication structure of Cal.com, remember to prepend the API key with `Bearer ` when creating the secret.
    </Warning>

    <Frame background="subtle">
      ![Tool secrets](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630/assets/images/conversational-ai/tool-secrets.jpg)
    </Frame>
  </Step>

  <Step title="Adding tools to the assistant">
    To enable your assistant to manage calendar bookings, we'll create two tools:

    1. **`get_available_slots`**: When a user asks, *"Is Louis free at 10:30 AM on Tuesday?"*, the assistant should use [Cal.com's "Get available slots" endpoint](https://cal.com/docs/api-reference/v2/slots/find-out-when-is-an-event-type-ready-to-be-booked) to check for available time slots.

    2. **`book_meeting`**: After identifying a suitable time, the assistant can proceed to book the meeting using [Cal.com's "Create a booking" endpoint](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking).

    First, head to the **Tools** section of your dashboard and choose **Add Tool**. Select **Webhook** as the Tool Type, then fill in the following sections:

    <AccordionGroup>
      <Accordion title="Tool 1: get_available_slots">
        <Tabs>
          <Tab title="Configuration">
            Metadata used by the assistant to determine when the tool should be called:

            | Field       | Value                                                                    |
            | ----------- | ------------------------------------------------------------------------ |
            | Name        | get\_available\_slots                                                    |
            | Description | This tool checks if a particular time slot is available in the calendar. |
            | Method      | GET                                                                      |
            | URL         | [https://api.cal.com/v2/slots](https://api.cal.com/v2/slots)             |
          </Tab>

          <Tab title="Headers">
            Matches the request headers defined [here](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots):

            | Type   | Name            | Value                               |
            | ------ | --------------- | ----------------------------------- |
            | Secret | Authorization   | Select the secret key created above |
            | String | cal-api-version | 2024-09-04                          |
          </Tab>

          <Tab title="Query parameters">
            Matches the request query parameters defined [here](https://cal.com/docs/api-reference/v2/slots/get-available-slots#get-available-slots):

            | Data Type | Identifier  | Required | Description                                                                                                               |
            | --------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
            | string    | start       | Yes      | Start date/time (UTC) from which to fetch slots, e.g. '2024-08-13T09:00:00Z'.                                             |
            | string    | end         | Yes      | End date/time (UTC) until which to fetch slots, e.g. '2024-08-13T17:00:00Z'.                                              |
            | string    | eventTypeId | Yes      | The ID of the event type that is booked. If 15 minutes, return abc. If 30 minutes, return def. If 60 minutes, return xyz. |
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="Tool 2: book_meeting">
        <Tabs>
          <Tab title="Configuration">
            Metadata used by the assistant to determine when the tool should be called:

            | Field       | Value                                                              |
            | ----------- | ------------------------------------------------------------------ |
            | Name        | book\_meeting                                                      |
            | Description | This tool books a meeting in the calendar once a time is agreed.   |
            | Method      | POST                                                               |
            | URL         | [https://api.cal.com/v2/bookings](https://api.cal.com/v2/bookings) |
          </Tab>

          <Tab title="Headers">
            Matches the request headers defined [here](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking):

            | Type   | Name            | Value                               |
            | ------ | --------------- | ----------------------------------- |
            | Secret | Authorization   | Select the secret key created above |
            | String | cal-api-version | 2024-08-13                          |
          </Tab>

          <Tab title="Body Parameters">
            Matches the request body parameters defined [here](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#create-a-booking):

            | Identifier  | Data Type | Required | Description                                                                                                               |
            | ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
            | start       | String    | Yes      | The start time of the booking in ISO 8601 format in UTC timezone, e.g. ‘2024-08-13T09:00:00Z’.                            |
            | eventTypeId | Number    | Yes      | The ID of the event type that is booked. If 15 minutes, return abc. If 30 minutes, return def. If 60 minutes, return xyz. |
            | attendee    | Object    | Yes      | The attendee's details. You must collect these fields from the user.                                                      |

            <Note>
              The `eventTypeId` must correspond to the event types you have available in Cal. Call
              [this](https://cal.com/docs/api-reference/v1/event-types/find-all-event-types#find-all-event-types)
              endpoint to get a list of your account event types (or create another tool that does this
              automatically).
            </Note>

            **Attendee object:**

            | Identifier | Data Type | Required | Description                                                                                                     |
            | ---------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------- |
            | name       | String    | Yes      | The full name of the person booking the meeting.                                                                |
            | email      | String    | Yes      | The email address of the person booking the meeting.                                                            |
            | timeZone   | String    | Yes      | The caller's timezone. Should be in the format of 'Continent/City' like 'Europe/London' or 'America/New\_York'. |
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>

    <Success>
      Test your new assistant by pressing the **Test AI agent** button to ensure everything is working
      as expected. Feel free to fine-tune the system prompt.
    </Success>
  </Step>

  <Step title="Enhancements">
    By default, the assistant does not have knowledge of the current date or time. To enhance its capabilities, consider implementing one of the following solutions:

    1. **Create a time retrieval tool**: Add another tool that fetches the current date and time.

    2. **Overrides**: Use the [overrides](/docs/agents-platform/customization/personalization/overrides) functionality to inject the current date and time into the system prompt at the start of each conversation.
  </Step>
</Steps>

## Security Considerations

* Use HTTPS endpoints for all webhook calls.
* Store sensitive values as secrets using the ElevenLabs Secrets Manager.
* Validate that all authorization headers follow the required format (`Bearer YOUR_API_KEY`).
* Never expose event type IDs or API details to callers.

## Conclusion

This guide details how to integrate Cal.com into our ElevenAgents for efficient meeting scheduling. By leveraging webhook tools and calendar availability data, the integration streamlines the booking process, reducing scheduling friction and enhancing overall service quality.

For additional details on tool configuration or other integrations, refer to the [Tools Overview](/docs/agents-platform/customization/tools/server-tools).


# Data Collection and Analysis with Agents Platform in Next.js

> Collect and analyse data in post-call webhooks using Agents Platform and Next.js.

## Introduction

In this tutorial you will learn how to build a voice agent that collects information from the user through conversation, then analyses and extracts the data in a structured way and sends it to your application via the post-call webhook.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/8b-r1xYdZkw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [example project on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/nextjs-post-call-webhook).
</Tip>

## Requirements

* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys).
* Node.js v18 or higher installed on your machine.

## Setup

### Create a new Next.js project

We recommend using our [v0.dev Agents Platform template](https://v0.dev/community/nextjs-5TN93pl3bRS) as the starting point for your application. This template is a production-ready Next.js application with the ElevenLabs agent already integrated.

Alternatively, you can clone the [fully integrated project from GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/conversational-ai/nextjs-post-call-webhook), or create a new blank Next.js project and follow the steps below to integrate the ElevenLabs agent.

### Set up Agents Platform

Follow our [Next.js guide](/docs/agents-platform/guides/quickstarts/next-js) for installation and configuration steps. Then come back here to build in the advanced features.

## Agent configuration

<Steps>
  <Step title="Sign in to ElevenLabs">
    Go to [elevenlabs.io](https://elevenlabs.io/app/sign-up) and sign in to your account.
  </Step>

  <Step title="Create a new agent">
    Navigate to [Agents Platform > Agents](https://elevenlabs.io/app/agents/agents) and
    create a new agent from the blank template.
  </Step>

  <Step title="Set the first message">
    Set the first message and specify the dynamic variable for the platform.

    ```txt
    Hi {{user_name}}, I'm Jess from the ElevenLabs team. I'm here to help you design your very own ElevenLabs agent! To kick things off, let me know what kind of agent you're looking to create. For example, do you want a support agent, to help your users answer questions, or a sales agent to sell your products, or just a friend to chat with?
    ```
  </Step>

  <Step title="Set the system prompt">
    Set the system prompt. You can also include dynamic variables here.

    ```txt
    You are Jess, a helpful agent helping {{user_name}} to design their very own ElevenLabs agent. The design process involves the following steps:

    "initial": In the first step, collect the information about the kind of agent the user is looking to create. Summarize the user's needs back to them and ask if they are ready to continue to the next step. Only once they confirm proceed to the next step.
    "training": Tell the user to create the agent's knowledge base by uploading documents, or submitting URLs to public websites with information that should be available to the agent. Wait patiently without talking to the user. Only when the user confirms that they've provided everything then proceed to the next step.
    "voice": Tell the user to describe the voice they want their agent to have. For example: "A professional, strong spoken female voice with a slight British accent." Repeat the description of their voice back to them and ask if they are ready to continue to the next step. Only once they confirm proceed to the next step.
    "email": Tell the user that we've collected all necessary information to create their ElevenLabs agent and ask them to provide their email address to get notified when the agent is ready.

    Always call the `set_ui_state` tool when moving between steps!
    ```
  </Step>

  <Step title="Set up the client tools">
    Set up the following client tool to navigate between the steps:

    * Name: `set_ui_state`
      * Description: Use this client-side tool to navigate between the different UI states.
      * Wait for response: `true`
      * Response timeout (seconds): 1
      * Parameters:
        * Data type: string
        * Identifier: step
        * Required: true
        * Value Type: LLM Prompt
        * Description: The step to navigate to in the UI. Only use the steps that are defined in the system prompt!
  </Step>

  <Step title="Set your agent's voice">
    Navigate to the `Voice` tab and set the voice for your agent. You can find a list of recommended voices for Agents Platform in the [Conversational Voice Design docs](/docs/agents-platform/customization/voice/best-practices/conversational-voice-design#voices).
  </Step>

  <Step title="Set the evaluation criteria">
    Navigate to the `Analysis` tab and add a new evaluation criteria.

    * Name: `all_data_provided`
      * Prompt: Evaluate whether the user provided a description of the agent they are looking to generate as well as a description of the voice the agent should have.
  </Step>

  <Step title="Configure the data collection">
    You can use the post call analysis to extract data from the conversation. In the `Analysis` tab, under `Data Collection`, add the following items:

    * Identifier: `voice_description`
      * `data-type`: `String`
      * Description: Based on the description of the voice the user wants the agent to have, generate a concise description of the voice including the age, accent, tone, and character if available.
    * Identifier: `agent_description`
      * `data-type`: `String`
      * Description: Based on the description about the agent the user is looking to design, generate a prompt that can be used to train a model to act as the agent.
  </Step>

  <Step title="Configure the post-call webhook">
    [Post-call webhooks](https://elevenlabs.io/docs/agents-platform/workflows/post-call-webhooks) are used to notify you when a call ends and the analysis and data extraction steps have been completed.

    In this example the, the post-call webhook does a couple of steps, namely:

    1. Create a custom voice design based on the `voice_description`.
    2. Create a ElevenLabs agent for the users based on the `agent_description` they provided.
    3. Retrieve the knowledge base documents from the conversation state stored in Redis and attach the knowledge base to the agent.
    4. Send an email to the user to notify them that their custom ElevenLabs agent is ready to chat.

    When running locally, you will need a tool like [ngrok](https://ngrok.com/) to expose your local server to the internet.

    ```bash
    ngrok http 3000
    ```

    Navigate to the [Agents Platform settings](https://elevenlabs.io/app/agents/settings) and under `Post-Call Webhook` create a new webhook and paste in your ngrok URL: `https://<your-url>.ngrok-free.app/api/convai-webhook`.

    After saving the webhook, you will receive a webhooks secret. Make sure to store this secret securely as you will need to set it in your `.env` file later.
  </Step>
</Steps>

## Integrate the advanced features

### Set up a Redis database for storing the conversation state

In this example we're using Redis to store the conversation state. This allows us to retrieve the knowledge base documents from the conversation state after the call ends.

If you're deploying to Vercel, you can configure the [Upstash for Redis](https://vercel.com/marketplace/upstash) integration, or alternatively you can sign up for a free [Upstash account](https://upstash.com/) and create a new database.

### Set up Resend for sending post-call emails

In this example we're using Resend to send the post-call email to the user. To do so you will need to create a free [Resend account](https://resend.com/) and set up a new API key.

### Set the environment variables

In the root of your project, create a `.env` file and add the following variables:

```bash
ELEVENLABS_CONVAI_WEBHOOK_SECRET=
ELEVENLABS_API_KEY=
ELEVENLABS_AGENT_ID=

# Resend
RESEND_API_KEY=
RESEND_FROM_EMAIL=

# Upstash Redis
KV_URL=
KV_REST_API_READ_ONLY_TOKEN=
REDIS_URL=
KV_REST_API_TOKEN=
KV_REST_API_URL=
```

### Configure security and authentication

To secure your ElevenLabs agent, you need to enable authentication in the `Security` tab of the agent configuration.

Once authentication is enabled, you will need to create a signed URL in a secure server-side environment to initiate a conversation with the agent. In Next.js, you can do this by setting up a new API route.

```tsx ./app/api/signed-url/route.ts
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import { NextResponse } from 'next/server';

export async function GET() {
  const agentId = process.env.ELEVENLABS_AGENT_ID;
  if (!agentId) {
    throw Error('ELEVENLABS_AGENT_ID is not set');
  }
  try {
    const elevenlabs = new ElevenLabsClient();
    const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
      agentId,
    });
    return NextResponse.json({ signedUrl: response.signedUrl });
  } catch (error) {
    console.error('Error:', error);
    return NextResponse.json({ error: 'Failed to get signed URL' }, { status: 500 });
  }
}
```

### Start the conversation session

To start the conversation, first, call your API route to get the signed URL, then use the `useConversation` hook to set up the conversation session.

```tsx ./page.tsx {1,4,20-25,31-46}
import { useConversation } from '@elevenlabs/react';

async function getSignedUrl(): Promise<string> {
  const response = await fetch('/api/signed-url');
  if (!response.ok) {
    throw Error('Failed to get signed url');
  }
  const data = await response.json();
  return data.signedUrl;
}

export default function Home() {
  // ...
  const [currentStep, setCurrentStep] = useState<
    'initial' | 'training' | 'voice' | 'email' | 'ready'
  >('initial');
  const [conversationId, setConversationId] = useState('');
  const [userName, setUserName] = useState('');

  const conversation = useConversation({
    onConnect: () => console.log('Connected'),
    onDisconnect: () => console.log('Disconnected'),
    onMessage: (message: string) => console.log('Message:', message),
    onError: (error: Error) => console.error('Error:', error),
  });

  const startConversation = useCallback(async () => {
    try {
      // Request microphone permission
      await navigator.mediaDevices.getUserMedia({ audio: true });
      // Start the conversation with your agent
      const signedUrl = await getSignedUrl();
      const convId = await conversation.startSession({
        signedUrl,
        dynamicVariables: {
          user_name: userName,
        },
        clientTools: {
          set_ui_state: ({ step }: { step: string }): string => {
            // Allow agent to navigate the UI.
            setCurrentStep(step as 'initial' | 'training' | 'voice' | 'email' | 'ready');
            return `Navigated to ${step}`;
          },
        },
      });
      setConversationId(convId);
      console.log('Conversation ID:', convId);
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [conversation, userName]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  // ...
}
```

### Client tool and dynamic variables

In the agent configuration earlier, you registered the `set_ui_state` client tool to allow the agent to navigate between the different UI states. To put it all together, you need to pass the client tool implementation to the `conversation.startSession` options.

This is also where you can pass in the dynamic variables to the conversation.

```tsx ./page.tsx {3-5,7-11}
const convId = await conversation.startSession({
  signedUrl,
  dynamicVariables: {
    user_name: userName,
  },
  clientTools: {
    set_ui_state: ({ step }: { step: string }): string => {
      // Allow agent to navigate the UI.
      setCurrentStep(step as 'initial' | 'training' | 'voice' | 'email' | 'ready');
      return `Navigated to ${step}`;
    },
  },
});
```

### Uploading documents to the knowledge base

In the `Training` step, the agent will ask the user to upload documents or submit URLs to public websites with information that should be available to their agent. Here you can utilise the new `after` function of [Next.js 15](https://nextjs.org/docs/app/api-reference/functions/after) to allow uploading of documents in the background.

Create a new `upload` server action to handle the knowledge base creation upon form submission. Once all knowledge base documents have been created, store the conversation ID and the knowledge base IDs in the Redis database.

```tsx ./app/actions/upload.ts {26,32,44,56-60}
'use server';

import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import { Redis } from '@upstash/redis';
import { redirect } from 'next/navigation';
import { after } from 'next/server';

// Initialize Redis
const redis = Redis.fromEnv();

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

export async function uploadFormData(formData: FormData) {
  const knowledgeBase: Array<{
    id: string;
    type: 'file' | 'url';
    name: string;
  }> = [];
  const files = formData.getAll('file-upload') as File[];
  const email = formData.get('email-input');
  const urls = formData.getAll('url-input');
  const conversationId = formData.get('conversation-id');

  after(async () => {
    // Upload files as background job
    // Create knowledge base entries
    // Loop through files and create knowledge base entries
    for (const file of files) {
      if (file.size > 0) {
        const response = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromFile({
          file,
        });
        if (response.id) {
          knowledgeBase.push({
            id: response.id,
            type: 'file',
            name: file.name,
          });
        }
      }
    }
    // Append all urls
    for (const url of urls) {
      const response = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromUrl({
        url: url as string,
      });
      if (response.id) {
        knowledgeBase.push({
          id: response.id,
          type: 'url',
          name: `url for ${conversationId}`,
        });
      }
    }

    // Store knowledge base IDs and conversation ID in database.
    const redisRes = await redis.set(
      conversationId as string,
      JSON.stringify({ email, knowledgeBase })
    );
    console.log({ redisRes });
  });

  redirect('/success');
}
```

## Handling the post-call webhook

The [post-call webhook](/docs/agents-platform/workflows/post-call-webhooks) is triggered when a call ends and the analysis and data extraction steps have been completed.

There's a few steps that are happening here, namely:

1. Verify the webhook secret and construct the webhook payload.
2. Create a custom voice design based on the `voice_description`.
3. Create a ElevenLabs agent for the users based on the `agent_description` they provided.
4. Retrieve the knowledge base documents from the conversation state stored in Redis and attach the knowledge base to the agent.
5. Send an email to the user to notify them that their custom ElevenLabs agent is ready to chat.

```ts ./app/api/convai-webhook/route.ts
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import { Redis } from '@upstash/redis';
import crypto from 'crypto';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { Resend } from 'resend';

import { EmailTemplate } from '../../../../../components/email/post-call-webhook-email';

// Initialize Redis
const redis = Redis.fromEnv();
// Initialize Resend
const resend = new Resend(process.env.RESEND_API_KEY);

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

export async function GET() {
  return NextResponse.json({ status: 'webhook listening' }, { status: 200 });
}

export async function POST(req: NextRequest) {
  const secret = process.env.ELEVENLABS_CONVAI_WEBHOOK_SECRET; // Add this to your env variables
  const { event, error } = await constructWebhookEvent(req, secret);
  if (error) {
    return NextResponse.json({ error: error }, { status: 401 });
  }

  if (event.type === 'post_call_transcription') {
    const { conversation_id, analysis, agent_id } = event.data;

    if (
      agent_id === process.env.ELEVENLABS_AGENT_ID &&
      analysis.evaluation_criteria_results.all_data_provided?.result === 'success' &&
      analysis.data_collection_results.voice_description?.value
    ) {
      try {
        // Design the voice
        const voicePreview = await elevenlabs.textToVoice.createPreviews({
          voiceDescription: analysis.data_collection_results.voice_description.value,
          text: 'The night air carried whispers of betrayal, thick as London fog. I adjusted my cufflinks - after all, even spies must maintain appearances, especially when the game is afoot.',
        });
        const voice = await elevenlabs.textToVoice.createVoiceFromPreview({
          voiceName: `voice-${conversation_id}`,
          voiceDescription: `Voice for ${conversation_id}`,
          generatedVoiceId: voicePreview.previews[0].generatedVoiceId,
        });

        // Get the knowledge base from redis
        const redisRes = await getRedisDataWithRetry(conversation_id);
        if (!redisRes) throw new Error('Conversation data not found!');
        // Handle agent creation
        const agent = await elevenlabs.conversationalAi.agents.create({
          name: `Agent for ${conversation_id}`,
          conversationConfig: {
            tts: { voiceId: voice.voiceId },
            agent: {
              prompt: {
                prompt:
                  analysis.data_collection_results.agent_description?.value ??
                  'You are a helpful assistant.',
                knowledgeBase: redisRes.knowledgeBase,
              },
              firstMessage: 'Hello, how can I help you today?',
            },
          },
        });
        console.log('Agent created', { agent: agent.agentId });
        // Send email to user
        console.log('Sending email to', redisRes.email);
        await resend.emails.send({
          from: process.env.RESEND_FROM_EMAIL!,
          to: redisRes.email,
          subject: 'Your ElevenLabs agent is ready to chat!',
          react: EmailTemplate({ agentId: agent.agentId }),
        });
      } catch (error) {
        console.error(error);
        return NextResponse.json({ error }, { status: 500 });
      }
    }
  }

  return NextResponse.json({ received: true }, { status: 200 });
}

const constructWebhookEvent = async (req: NextRequest, secret?: string) => {
  const body = await req.text();
  const signatureHeader = req.headers.get('ElevenLabs-Signature');

  return await elevenlabs.webhooks.constructEvent(body, signatureHeader, secret);
};

async function getRedisDataWithRetry(
  conversationId: string,
  maxRetries = 5
): Promise<{
  email: string;
  knowledgeBase: Array<{
    id: string;
    type: 'file' | 'url';
    name: string;
  }>;
} | null> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const data = await redis.get(conversationId);
      return data as any;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.log(`Redis get attempt ${attempt} failed, retrying...`);
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }
  return null;
}
```

Let's go through each step in detail.

### Verify the webhook secret and consrtuct the webhook payload

When the webhook request is received, we first verify the webhook secret and construct the webhook payload.

```ts ./app/api/convai-webhook/route.ts
// ...

export async function POST(req: NextRequest) {
  const secret = process.env.ELEVENLABS_CONVAI_WEBHOOK_SECRET;
  const { event, error } = await constructWebhookEvent(req, secret);
  // ...
}

// ...
const constructWebhookEvent = async (req: NextRequest, secret?: string) => {
  const body = await req.text();
  const signatureHeader = req.headers.get('ElevenLabs-Signature');

  return await elevenlabs.webhooks.constructEvent(body, signatureHeader, secret);
};

async function getRedisDataWithRetry(
  conversationId: string,
  maxRetries = 5
): Promise<{
  email: string;
  knowledgeBase: Array<{
    id: string;
    type: 'file' | 'url';
    name: string;
  }>;
} | null> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const data = await redis.get(conversationId);
      return data as any;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.log(`Redis get attempt ${attempt} failed, retrying...`);
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }
  return null;
}
```

### Create a custom voice design based on the `voice_description`

Using the `voice_description` from the webhook payload, we create a custom voice design.

```ts ./app/api/convai-webhook/route.ts {5}
// ...

// Design the voice
const voicePreview = await elevenlabs.textToVoice.createPreviews({
  voiceDescription: analysis.data_collection_results.voice_description.value,
  text: 'The night air carried whispers of betrayal, thick as London fog. I adjusted my cufflinks - after all, even spies must maintain appearances, especially when the game is afoot.',
});
const voice = await elevenlabs.textToVoice.createVoiceFromPreview({
  voiceName: `voice-${conversation_id}`,
  voiceDescription: `Voice for ${conversation_id}`,
  generatedVoiceId: voicePreview.previews[0].generatedVoiceId,
});

// ...
```

### Retrieve the knowledge base documents from the conversation state stored in Redis

The uploading of the documents might take longer than the webhook data analysis, so we'll need to poll the conversation state in Redis until the documents have been uploaded.

```ts ./app/api/convai-webhook/route.ts
// ...

// Get the knowledge base from redis
const redisRes = await getRedisDataWithRetry(conversation_id);
if (!redisRes) throw new Error('Conversation data not found!');
// ...

async function getRedisDataWithRetry(
  conversationId: string,
  maxRetries = 5
): Promise<{
  email: string;
  knowledgeBase: Array<{
    id: string;
    type: 'file' | 'url';
    name: string;
  }>;
} | null> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const data = await redis.get(conversationId);
      return data as any;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.log(`Redis get attempt ${attempt} failed, retrying...`);
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }
  return null;
}
```

### Create a ElevenLabs agent for the users based on the `agent_description` they provided

Create the ElevenLabs agent for the user based on the `agent_description` they provided and attach the newly created voice design and knowledge base to the agent.

```ts ./app/api/convai-webhook/route.ts {7,11}
// ...

// Handle agent creation
const agent = await elevenlabs.conversationalAi.agents.create({
  name: `Agent for ${conversationId}`,
  conversationConfig: {
    tts: { voiceId: voice.voiceId },
    agent: {
      prompt: {
        prompt:
          analysis.data_collection_results.agent_description?.value ??
          'You are a helpful assistant.',
        knowledgeBase: redisRes.knowledgeBase,
      },
      firstMessage: 'Hello, how can I help you today?',
    },
  },
});
console.log('Agent created', { agent: agent.agentId });

// ...
```

### Send an email to the user to notify them that their custom ElevenLabs agent is ready to chat

Once the agent is created, you can send an email to the user to notify them that their custom ElevenLabs agent is ready to chat.

```ts ./app/api/convai-webhook/route.ts
import { Resend } from 'resend';

import { EmailTemplate } from '../../../../../components/email/post-call-webhook-email';

// ...

// Send email to user
console.log('Sending email to', redisRes.email);
await resend.emails.send({
  from: process.env.RESEND_FROM_EMAIL!,
  to: redisRes.email,
  subject: 'Your ElevenLabs agent is ready to chat!',
  react: EmailTemplate({ agentId: agent.agentId }),
});

// ...
```

You can use [new.email](https://new.email/), a handy tool from the Resend team, to vibe design your email templates. Once you're happy with the template, create a new component and add in the agent ID as a prop.

```tsx ./components/email/post-call-webhook-email.tsx {14}
import {
  Body,
  Button,
  Container,
  Head,
  Html,
  Section,
  Text,
  Tailwind,
} from '@react-email/components';
import * as React from 'react';

const EmailTemplate = (props: any) => {
  const { agentId } = props;
  return (
    <Html>
      <Head />
      <Tailwind>
        <Body className="bg-[#151516] font-sans">
          <Container className="mx-auto my-[40px] max-w-[600px] rounded-[8px] bg-[#0a1929] p-[20px]">
            {/* Top Section */}
            <Section className="mb-[32px] mt-[32px] text-center">
              <Text className="m-0 text-[28px] font-bold text-[#9c27b0]">
                Your ElevenLabs agent is ready to chat!
              </Text>
            </Section>

            {/* Content Area with Icon */}
            <Section className="mb-[32px] text-center">
              {/* Circle Icon with Checkmark */}
              <div className="mx-auto mb-[24px] flex h-[80px] w-[80px] items-center justify-center rounded-full bg-gradient-to-r from-[#9c27b0] to-[#3f51b5]">
                <div className="text-[40px] text-white">✓</div>
              </div>

              {/* Descriptive Text */}
              <Text className="mb-[24px] text-[18px] text-white">
                Your ElevenLabs agent is ready to chat!
              </Text>
            </Section>

            {/* Call to Action Button */}
            <Section className="mb-[32px] text-center">
              <Button
                href={`https://elevenlabs.io/app/talk-to?agent_id=${agentId}`}
                className="box-border rounded-[8px] bg-[#9c27b0] px-[40px] py-[20px] text-[24px] font-bold text-white no-underline"
              >
                Chat now!
              </Button>
            </Section>

            {/* Footer */}
            <Section className="mt-[40px] border-t border-[#2d3748] pt-[20px] text-center">
              <Text className="m-0 text-[14px] text-white">
                Powered by{' '}
                <a
                  href="https://elevenlabs.io/conversational-ai"
                  target="_blank"
                  rel="noopener noreferrer"
                  className="underline transition-colors hover:text-gray-400"
                >
                  ElevenLabs Agents
                </a>
              </Text>
            </Section>
          </Container>
        </Body>
      </Tailwind>
    </Html>
  );
};

export { EmailTemplate };
```

## Run the app

To run the app locally end-to-end, you will need to first run the Next.js development server, and then in a separate terminal run the ngrok tunnel to expose the webhook handler to the internet.

* Terminal 1:
  * Run `pnpm dev` to start the Next.js development server.

```bash
pnpm dev
```

* Terminal 2:
  * Run `ngrok http 3000` to expose the webhook handler to the internet.

```bash
ngrok http 3000
```

Now open [http://localhost:3000](http://localhost:3000) and start designing your custom ElevenLabs agent, with your voice!

## Conclusion

[ElevenLabs Agents](https://elevenlabs.io/conversational-ai) is a powerful platform for building advanced voice agent uses cases, complete with data collection and analysis.


# Zendesk

> Learn how to integrate our ElevenAgents with Zendesk for better customer support

## Overview

With our Zendesk integration, your support agent can quickly identify and resolve customer issues by leveraging historical ticket data. This integration streamlines the support process by automatically checking for similar resolved issues, advising customers based on past resolutions, and securely creating new support tickets. Benefits include faster resolutions, reduced manual effort, and enhanced customer satisfaction.

## Demo Video

Watch the demonstration of the Zendesk + ElevenAgents integration.

<Frame background="subtle" caption="Zendesk Integration Demo">
  <iframe src="https://www.loom.com/embed/109404cb8aa348f5ab019feeec292c95?sid=87f90604-fb6e-421f-abed-09d571b6b46f" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen />
</Frame>

## How it works

We lay out below how we have configured the ElevenLabs agent to resolve tickets by using tool calling to step through the resolution process.
Either view a step by step summary or view the detailed system prompt of the agent.

<Tabs>
  <Tab title="High level overview ">
    <Steps>
      <Step title="Initial Inquiry & Issue Details">
        Configure your agent to ask for a detailed description of the support issue and follow up with focused questions to gather all necessary information.
      </Step>

      <Step title="Check for Similar Issues">
        Configure the agent to check historical tickets for similar issues by:

        * Using the `get_resolved_tickets` tool to fetch past tickets
        * Finding similar tickets and their resolutions
        * Extracting relevant comments via the `get_ticket_comments` tool
        * Using this information to suggest proven solutions
      </Step>

      <Step title="Contact Information Collection">
        If the ticket can't be deflected:

        * Collect and validate the customer's full name
        * Verify email address accuracy
        * Confirm any additional required fields for your Zendesk setup
      </Step>

      <Step title="Ticket Creation">
        * Use the `zendesk_open_ticket` tool after information verification
        * Follow the ticket template structure
        * Confirm ticket creation with the customer
        * Inform them that support will be in touch
      </Step>
    </Steps>
  </Tab>

  <Tab title="Detailed system prompt">
    ```
    You are a helpful ElevenLabs support agent responsible for gathering information from users and creating support tickets using the zendesk_open_ticket tool. Be friendly, precise, and concise.

    Begin by briefly asking asking for a detailed description of the problem.
    Then, ask relevant support questions to gather additional details, one question at a time, and wait for the user's response before proceeding.

    Once you have a description of the issue, say you will check if there are similar issues and any known resolutions.
    - call get_resolved_tickets
    - find the ticket which has the most similar issue to that of the caller
    - call get_ticket_comments, using the result id from the previous response
    - get any learnings from the resolution of this ticket

    After this, tell the customer the recommended resolution from a previous similar issue. If they have already tried it or still want to move forward, move to the ticket creation step. Only provide resolution advice derived from the comments.

    After capturing the support issue, gather the following contact details:
    - The user's name.
    - A valid email address for the requestor. Note that the email address is transcribed from voice, so ensure it is formatted correctly.
    - Read the email back to the caller to confirm accuracy.

    Once the email is confirmed, explain that you will create the ticket.
    Create the ticket by using the Tool zendesk_open_ticket. Add these details to the ticket comment body.
    Thank the customer and say support will be in touch.

    Clarifications:
    - Do not inform the user that you are formatting the email; simply do it.
    - If the caller asks you to move forward with creating the ticket, do so with the existing information.

    Guardrails:
    - Do not speak about topics outside of support issues with ElevenLabs.
    ```
  </Tab>
</Tabs>

<Tip>
  This integration enhances efficiency by leveraging historical support data. All API calls require
  proper secret handling in the authorization headers.
</Tip>

## Authentication Setup

Before configuring the tools, you must set up authentication with Zendesk.

### Step 1: Generate Zendesk API Token

1. Log into your Zendesk admin panel
2. Go to **Admin → Channels → API**
3. Enable **Token access** if not already enabled
4. Click **Add API token**
5. Copy the generated token - you'll need it for the next step

### Step 2: Create Authentication Secret

The Zendesk API requires Basic authentication. You need to create a properly formatted secret:

1. **Format your credentials** using this pattern:

   ```
   {your_email}/token:{your_api_token}
   ```

   **Example:**

   ```
   jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv
   ```

2. **Base64 encode** the formatted string

   * You can use the command line option: `echo -n "your_string" | base64`

3. **Create the final secret value** by adding "Basic " prefix:

   ```
   Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2
   ```

4. **Save this as a secret** in your agent's secrets with name `zendesk_key`

## Tool Configurations

The integration with zendesk employs three webhook tools to create the support agent. Use the tabs below to review each tool's configuration.

<Tabs>
  <Tab title="zendesk_get_ticket_comments">
    **Name:** zendesk\_get\_ticket\_comments
    **Description:** Retrieves the comments of a ticket.
    **Method:** GET
    **URL:** `https://your-subdomain.zendesk.com/api/v2/tickets/{ticket_id}/comments.json`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `zendesk_key`)*

    **Path Parameters:**

    * **ticket\_id:** Extract the value from the `id` field in the get\_resolved\_tickets results.

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "type": "webhook",
      "name": "zendesk_get_ticket_comments",
      "description": "Retrieves the comments of a ticket.",
      "api_schema": {
        "url": "https://your-subdomain.zendesk.com/api/v2/tickets/{ticket_id}/comments.json",
        "method": "GET",
        "path_params_schema": [
          {
            "id": "ticket_id",
            "type": "string",
            "description": "Extract the value from the id field in the get_resolved_tickets results.",
            "dynamic_variable": "",
            "constant_value": "",
            "required": false,
            "value_type": "llm_prompt"
          }
        ],
        "query_params_schema": [],
        "request_body_schema": null,
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          },
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="zendesk_get_resolved_tickets">
    **Name:** zendesk\_get\_resolved\_tickets
    **Description:** Retrieves all resolved support tickets from Zendesk.
    **Method:** GET
    **URL:** `https://your-subdomain.zendesk.com/api/v2/search.json?query=type:ticket+status:solved`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `zendesk_key`)*

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "type": "webhook",
      "name": "zendesk_get_resolved_tickets",
      "description": "Retrieves all resolved support tickets from Zendesk.",
      "api_schema": {
        "url": "https://your-subdomain.zendesk.com/api/v2/search.json?query=type:ticket+status:solved",
        "method": "GET",
        "path_params_schema": [],
        "query_params_schema": [],
        "request_body_schema": null,
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          },
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="zendesk_open_ticket">
    **Name:** zendesk\_open\_ticket
    **Description:** Opens a new support ticket.
    **Method:** POST
    **URL:** `https://your-subdomain.zendesk.com/api/v2/tickets.js`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `zendesk_key`)*

    **Body Parameters:**

    * **ticket:** An object containing:
      * **comment:**
        * **body:** Detailed description of the support issue.
      * **subject:** A short subject line.
      * **requester:**
        * **name:** The full name of the requester.
        * **email:** A valid email address.

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "type": "webhook",
      "name": "zendesk_open_ticket",
      "description": "API endpoint to open a customer support ticket\nMake sure the authorization header is formated as \"Authorization: Basic <auth>\".",
      "api_schema": {
        "url": "https://your-subdomain.zendesk.com/api/v2/tickets.js",
        "method": "POST",
        "path_params_schema": [],
        "query_params_schema": [],
        "request_body_schema": {
          "id": "body",
          "type": "object",
          "description": "Details for the support ticket",
          "required": false,
          "properties": [
            {
              "id": "ticket",
              "type": "object",
              "description": "This is the main ticket body which contains all of the information needed to open a ticket.",
              "required": true,
              "properties": [
                {
                  "id": "comment",
                  "type": "object",
                  "description": "This is the comment with information about the issue.",
                  "required": true,
                  "properties": [
                    {
                      "id": "body",
                      "type": "string",
                      "description": "Body of the issue. Include all relevant details for the issue. ",
                      "dynamic_variable": "",
                      "constant_value": "",
                      "required": true,
                      "value_type": "llm_prompt"
                    }
                  ]
                },
                {
                  "id": "subject",
                  "type": "string",
                  "description": "Create a short subject line for the support issue. Add \"DEMO: \" before the subject.",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "requester",
                  "type": "object",
                  "description": "The details of the support requester",
                  "required": true,
                  "properties": [
                    {
                      "id": "email",
                      "type": "string",
                      "description": "The email address of the requester. This should look like \njohnsmith@hotmail.com\nYou MUST use the @ symbol and remove any spaces.",
                      "dynamic_variable": "",
                      "constant_value": "",
                      "required": true,
                      "value_type": "llm_prompt"
                    },
                    {
                      "id": "name",
                      "type": "string",
                      "description": "The full name of the requester. ",
                      "dynamic_variable": "",
                      "constant_value": "",
                      "required": true,
                      "value_type": "llm_prompt"
                    }
                  ]
                }
              ]
            }
          ]
        },
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          },
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Ensure that you add your workspace's zendesk secret to the agent's secrets.
</Warning>

## Evaluation Configuration

To improve the observability of customer interactions, we configure the agent with the following evaluation criteria and data collection parameters.

<Frame background="subtle" caption="Track how well the AI agent performs against key evaluation criteria like issue relevance, sentiment, and resolution success.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7a2f0bb771e9e5dce8c543b988890c3d2febbd41b456b533080825ba8ac0b20e/assets/images/conversational-ai/zendesk_analysis.png" alt="Evaluation criteria for support interactions" />
</Frame>

These settings are added directly to the agent's configuration in the "Analysis" tab to ensure comprehensive monitoring of all customer interactions. This enables us to track performance, identify areas for improvement, and maintain high-quality support standards.

## Impact

With this integration in place, not only can you resolve tickets faster, but you can also reduce the load on your support team by deflecting tickets that are not relevant to your team.

In addition, you can use ElevenAgents to monitor the agent's usage.

<Frame background="subtle" caption="Get a high-level overview of each conversation and listen to the conversation's audio recording.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/f5727a3a4cb3b3b0b9eae6892db56a2f24c5bad7a15f822bbe644aa14aca213c/assets/images/conversational-ai/zendesk_conv_overview.png" alt="Support agent conversation summary" />
</Frame>

<Frame background="subtle" caption="Track how well the AI agent performs against key evaluation criteria like issue relevance, sentiment, and resolution success.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/1e6a905998718cf42c0e175776e9043915519f256ddc378689dbbd9848e50b38/assets/images/conversational-ai/zendesk_criteria_eval.png" alt="Evaluation criteria for support interactions" />
</Frame>

<Frame background="subtle" caption="Monitor the data collected during each interaction, including tools used, issue details, and customer information.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a3be54175bbaedf2a662585aefb4191822541fcb07258854dfbf38b3a912dc9a/assets/images/conversational-ai/zendesk_data_collection.png" alt="Data collection parameters from conversation transcripts" />
</Frame>

<Frame background="subtle" caption="Review detailed transcripts of conversations to understand agent performance, tool usage and customer interactions.">
  <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/caf81900840e71ab4f081ce2beee8aaf4e0c41d2e36f2f08e00786c9f96f4788/assets/images/conversational-ai/zendesk_transcript.png" alt="Detailed conversation transcript example" />
</Frame>

## Security Considerations

* Use HTTPS endpoints for all webhook calls.
* Store sensitive values as secrets using the ElevenLabs Secrets Manager.
* Validate that all authorization headers follow the required format.

## Conclusion

This guide details how to integrate Zendesk into our ElevenAgents for efficient support ticket management. By leveraging webhook tools and historical support data, the integration streamlines the support process, reducing resolution times and enhancing overall service quality.

For additional details on tool configuration or other integrations, refer to the [Tools Overview](/docs/agents-platform/customization/tools/server-tools).


# HubSpot

> Learn how to integrate our ElevenAgents with HubSpot CRM

## Overview

Leveraging the HubSpot integration, your agent can interact with your CRM both to retrieve and write relevant information about contacts, interactions, or follow ups.

## Demo video

Watch the demonstration of the HubSpot + ElevenAgents integration.

<Frame background="subtle" caption="HubSpot Integration Demo">
  <iframe src="https://www.loom.com/embed/cfb64cb7fc2a406489ef96e7c47d14c0?sid=f29bd120-8f33-4e34-a02b-85184da8deb2" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen />
</Frame>

## How it works

Here is an example of how a ElevenLabs agent can interact with your HubSpot CRM using tool calling.
Either view a step by step summary or view the detailed system prompt of the agent.

<Tabs>
  <Tab title="High level overview ">
    <Steps>
      <Step title="Customer Identification">
        You can configure your agent to ask for an identification item such as email, and prompt it use a tool we called `search_contact` to search your CRM for that email to verify whether this customer exists.
      </Step>

      <Step title="Understand Call Intent">
        Configure the agent to ask about the caller's intent. This can be adapted to meet your particular workflow.
      </Step>

      <Step title="Get previous interactions">
        While previous interactions can also be fetched and passed at the beginning of the conversation (see [Personalization](/docs/agents-platform/customization/personalization)). In this case we are fetching them during the conversation with two tool calls:

        * The tool `get_previous_calls` will fetch the previous conversations, using the contact ID retrieved during identification.
        * The response does not include the content of those conversations, so we need to use another endpoint to fetch the content with those call IDs.
      </Step>

      <Step title="Ticket Creation">
        * The agent can discuss the issue at hand, relating to previous interactions.
        * Use the `create_ticket` tool to create a ticket for a follow up item
        * Associate the ticket created to the CRM contact
      </Step>
    </Steps>
  </Tab>

  <Tab title="Detailed system prompt">
    ```
    # Personality

    You are a customer support agent. You are helpful, efficient, and polite. Your goal is to quickly understand the caller's issue and create a support ticket.

    # Environment

    You are answering a phone call from a customer. You have access to tools to search for customer contact information, previous calls and create tickets.

    # Tone

    You are professional and courteous. You speak clearly and concisely. You use a friendly tone and show empathy for the customer's situation. You confirm information to ensure accuracy.

    # Goal

    Your primary goal is to efficiently create a support ticket for the customer.

    1.  **Verify Identity:** Ask the caller for their email address to verify their identity. Silently use the `search_contact` tool to verify the caller exists. Use their name after this.
    2.  **Understand Issue:** Ask the customer what they are calling about and actively listen to capture their intent.
    3.  **Get previous interactions:**: Silently (without saying you will do it) call get_previous_calls and immediately after call get_call_content with the call ids, to see if previous interactions are relevant to the issue. Ask about their problem, and reference previous conversations if relevant. Use this information with the user.
    4.  **Create Ticket:** If the user wants to report an issue, make a new purchase, or discuss something else, use the `create_ticket` tool to create a ticket with the details of the customer's issue. Extract the description from the conversation.
    5.  **Confirmation:** Confirm the ticket details with the customer and communicate the ticket number to the caller, and mention a dedicated advisor will be in touch.

    # Guardrails

    *   Only use the tools provided.
    *   Do not provide information that is not related to the customer.
    *   Do not ask for personal information beyond what is needed to verify identity.
    *   Remain polite and professional at all times, even if the customer is upset.
    *   If you cannot create a ticket, explain why and offer alternative solutions.

    # Tools

    *   `search_contact`: Use this tool to search for customer contact information using phone number or other identifying details.
    *   `create_ticket`: Use this tool to create a support ticket with the customer's issue. Capture the customer's description of the issue accurately.
    *   `get_previous_calls`: Use this tool to fetch previous interactions with the customer.
    *   `get_call_content`: Use this tool to get the content of the previous interactions with the customer.

    ```
  </Tab>
</Tabs>

<Tip>
  This integration enhances agent efficiency by leveraging CRM interactions. All API calls require
  proper secret handling in the authorization headers.
</Tip>

## Authentication Setup

Before configuring the tools, you must set up authentication with HubSpot.

### Step 1: Generate HubsPot API Token

1. Log into your HubSpot account
2. Navigate to **Account Management → Integrations → Private Apps**
3. Create a **Private App**
4. Add the required scopes to the private app, to ensure it can interact with the required endpoints

```
crm.objects.contacts.read
crm.objects.contacts.write
crm.schemas.contacts.read
crm.schemas.contacts.write
tickets
```

5. Save and get the Access token from the Auth section

### Step 2: Create Authentication Secret

The HubSpot API requires Bearer authentication. You need to create a properly formatted secret:

1. **Create the secret value** by adding "Bearer " prefix:

   ```
   Bearer pat-eu1-12345678-abcdefgh-ijklmnop-qrstuvwx
   ```

2. **Save this as a secret** in your agent's secrets with name `hubspot_key`

## Tool Configurations

This sample integration with HubSpot employs four webhook tools. Use the tabs below to review each tool's configuration.

<Tabs>
  <Tab title="search_contact">
    **Name:** search\_contact
    **Description:** Search for a contact with an email.
    **Method:** POST
    **URL:** `https://api.hubapi.com/crm/v3/objects/contacts/search`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `hubspot_key`)*

    **Body Parameters:**

    * **filtersGroups:** An array containing:
      * An object containing:
        * **filters:** An array containing:
          * An object containing:
            * **value:** A string with description: `Set to the email provided by the user. Email should be in format: "name@address.com"`
            * **propertyName:** A string with description: `Set to: "email"`
            * **operator:** A string with description: `Set to: "CONTAINS_TOKEN"`

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "id": "tool_01jxftmwvxfgersp4aw0xhyhea",
      "type": "webhook",
      "name": "search_contact",
      "description": "search for a contact using phone",
      "api_schema": {
        "url": "https://api.hubapi.com/crm/v3/objects/contacts/search",
        "method": "POST",
        "path_params_schema": [],
        "query_params_schema": [],
        "request_body_schema": {
          "id": "body",
          "type": "object",
          "description": "filters for searching contacts",
          "required": false,
          "properties": [
            {
              "id": "filterGroups",
              "type": "array",
              "description": "filters group",
              "required": true,
              "items": {
                "type": "object",
                "description": "filters",
                "properties": [
                  {
                    "id": "filters",
                    "type": "array",
                    "description": "filters",
                    "required": true,
                    "items": {
                      "type": "object",
                      "description": "filters",
                      "properties": [
                        {
                          "id": "value",
                          "type": "string",
                          "description": "Set to the email provided by the user. Email should be in format: \n\n\"oscar@gmail.com\"",
                          "dynamic_variable": "",
                          "constant_value": "",
                          "required": true,
                          "value_type": "llm_prompt"
                        },
                        {
                          "id": "propertyName",
                          "type": "string",
                          "description": "Set to: \"email\"",
                          "dynamic_variable": "",
                          "constant_value": "",
                          "required": true,
                          "value_type": "llm_prompt"
                        },
                        {
                          "id": "operator",
                          "type": "string",
                          "description": "Set to: \"CONTAINS_TOKEN\"",
                          "dynamic_variable": "",
                          "constant_value": "",
                          "required": true,
                          "value_type": "llm_prompt"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "request_headers": [
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          },
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="get_previous_calls">
    **Name:** get\_previous\_calls
    **Description:** Retrieves the calls associated with a contact.
    **Method:** GET
    **URL:** `https://api.hubapi.com/crm/v3/objects/contacts/{CONTACT_ID}/associations/calls?limit=100`

    **Headers:**

    * **Authorization:** *(Secret: `hubspot_key`)*

    **Path Parameters:**

    * **CONTACT\_ID:** An string with description: `Use the contact ID from the results of the search_contact tool`

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "id": "tool_01jxfv4pttep6bbjaqe9tjk28n",
      "type": "webhook",
      "name": "get_previous_calls",
      "description": "This API retrieves the calls associated with a contact",
      "api_schema": {
        "url": "https://api.hubapi.com/crm/v3/objects/contacts/{CONTACT_ID}/associations/calls?limit=100",
        "method": "GET",
        "path_params_schema": [
          {
            "id": "CONTACT_ID",
            "type": "string",
            "description": "use the contact ID from the results of the search_contact tool",
            "dynamic_variable": "",
            "constant_value": "",
            "required": false,
            "value_type": "llm_prompt"
          }
        ],
        "query_params_schema": [],
        "request_body_schema": null,
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="get_call_content">
    **Name:** get\_call\_content
    **Description:** Use the call ids to get call content.
    **Method:** POST
    **URL:** `https://api.hubapi.com/crm/v3/objects/calls/batch/read`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `hubspot_key`)*

    **Body Parameters:**

    * **inputs:** An Array containing:
      * An Object containing:
        * **id:** A string with description: `Pass the ID of the call from the get_previous_calls response`
        * **body:** Detailed description of the support issue.
    * **properties:** An Array containing.
      * A string with description: `Set to: "hs_call_body"`

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "id": "tool_01jxhmfbg4e35s59kg6994vtt5",
      "type": "webhook",
      "name": "get_call_content",
      "description": "Use the call ids to get call content",
      "api_schema": {
        "url": "https://api.hubapi.com/crm/v3/objects/calls/batch/read",
        "method": "POST",
        "path_params_schema": [],
        "query_params_schema": [],
        "request_body_schema": {
          "id": "body",
          "type": "object",
          "description": "body params",
          "required": false,
          "properties": [
            {
              "id": "inputs",
              "type": "array",
              "description": "inputs",
              "required": true,
              "items": {
                "type": "object",
                "description": "inputs",
                "properties": [
                  {
                    "id": "id",
                    "type": "string",
                    "description": "pass the ID of the call from the get_previous_calls response",
                    "dynamic_variable": "",
                    "constant_value": "",
                    "required": true,
                    "value_type": "llm_prompt"
                  }
                ]
              }
            },
            {
              "id": "properties",
              "type": "array",
              "description": "properties",
              "required": true,
              "items": {
                "type": "string",
                "description": "Set to: \n\n\"hs_call_body\"",
                "constant_value": ""
              }
            }
          ]
        },
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          },
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="create_ticket">
    **Name:** create\_ticket
    **Description:** Call this tool to create a ticket.
    **Method:** POST
    **URL:** `https://api.hubapi.com/crm/v3/objects/tickets`

    **Headers:**

    * **Content-Type:** `application/json`
    * **Authorization:** *(Secret: `hubspot_key`)*

    **Body Parameters:**

    * **associations:** An Array containing:
      * An Object containing:
        * **to:** An object containing:
          * **id:** A string with description: `Set to the contact ID derived from the search_contact tool response`
          * **types:** An array containing:
            * An Object containing:
              * **associationCategory:** An string with description: `set to: "HUBSPOT_DEFINED"`
              * **associationTypeId:** An number with description: `Set to: 16"`
    * **properties:** An Object containing:
      * **content:** A string with description: `The content of the ticket`
      * **subject:** A string with description: `The subject of the ticket`
      * **hs\_pipeline:** A string with description: `Default to "0"`
      * **hs\_ticket\_priority:** A string with description: `Default to "HIGH"`
      * **hs\_pipeline\_stage:** A string with description: `Default to "1"`

    **Tool JSON:**

    Here is the tool JSON that can be copied into the tool config:

    ```json
    {
      "id": "tool_01jxftnpj8fx6rx2bwgbgmyjy7",
      "type": "webhook",
      "name": "create_ticket",
      "description": "Call this tool to create a ticket",
      "api_schema": {
        "url": "https://api.hubapi.com/crm/v3/objects/tickets",
        "method": "POST",
        "path_params_schema": [],
        "query_params_schema": [],
        "request_body_schema": {
          "id": "body",
          "type": "object",
          "description": "The properties of the ticket",
          "required": false,
          "properties": [
            {
              "id": "associations",
              "type": "array",
              "description": "associations",
              "required": true,
              "items": {
                "type": "object",
                "description": "associations",
                "properties": [
                  {
                    "id": "to",
                    "type": "object",
                    "description": "to",
                    "required": true,
                    "properties": [
                      {
                        "id": "id",
                        "type": "string",
                        "description": "set to the contact ID derived from the search_contact tool response",
                        "dynamic_variable": "",
                        "constant_value": "",
                        "required": true,
                        "value_type": "llm_prompt"
                      }
                    ]
                  },
                  {
                    "id": "types",
                    "type": "array",
                    "description": "types",
                    "required": true,
                    "items": {
                      "type": "object",
                      "description": "types",
                      "properties": [
                        {
                          "id": "associationCategory",
                          "type": "string",
                          "description": "set to: \"HUBSPOT_DEFINED\"",
                          "dynamic_variable": "",
                          "constant_value": "",
                          "required": true,
                          "value_type": "llm_prompt"
                        },
                        {
                          "id": "associationTypeId",
                          "type": "number",
                          "description": "Set to: 16",
                          "dynamic_variable": "",
                          "constant_value": "",
                          "required": true,
                          "value_type": "llm_prompt"
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "id": "properties",
              "type": "object",
              "description": "The properties of the ticket",
              "required": true,
              "properties": [
                {
                  "id": "content",
                  "type": "string",
                  "description": "The content of the ticket",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "subject",
                  "type": "string",
                  "description": "The subject of the ticket",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "hs_pipeline",
                  "type": "string",
                  "description": "Default to \"0\"",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "hs_ticket_priority",
                  "type": "string",
                  "description": "Default to \"HIGH\"",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                },
                {
                  "id": "hs_pipeline_stage",
                  "type": "string",
                  "description": "Default to \"1\"",
                  "dynamic_variable": "",
                  "constant_value": "",
                  "required": true,
                  "value_type": "llm_prompt"
                }
              ]
            }
          ]
        },
        "request_headers": [
          {
            "type": "secret",
            "name": "Authorization",
            "secret_id": "YOUR SECRET"
          },
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 20,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Ensure that you add your workspace's HubSpot secret to the agent's secrets.
</Warning>

## Security Considerations

* Use HTTPS endpoints for all webhook calls.
* Store sensitive values as secrets using the ElevenLabs Secrets Manager.
* Validate that all authorization headers follow the required format.

## Conclusion

This guide details how to integrate HubSpot CRM with our ElevenAgents. By leveraging webhook tools, the integration empowers AI agents to act more effectively in usecases such as sales, customer management, or support.

For additional details on tool configuration or other integrations, refer to the [Tools Overview](/docs/agents-platform/customization/tools/server-tools).


# Salesforce

> Learn how to integrate our ElevenAgents with Salesforce for enhanced customer relationship management

## Overview

Your ElevenLabs agents can access customer data, manage leads, and create opportunities directly within Salesforce. You can streamline CRM processes by automatically retrieving customer information, checking for existing records, and securely creating new records like leads and opportunities. Benefits include faster customer qualification, reduced manual data entry, and enhanced customer experience through personalized interactions.

## Demo Video

Watch the demonstration of the Salesforce & ElevenAgents integration.

<Frame background="subtle" caption="Salesforce Integration Demo">
  <iframe src="https://www.loom.com/embed/890054b55bc64c98b7de69905fc3e6b4?sid=a5cd24f5-fd1f-4c63-9794-9d0e3127cd26" frameBorder="0" webkitAllowFullScreen={true} mozAllowFullScreen={true} allowFullScreen={true} />
</Frame>

## How it works

We lay out below how we have configured the ElevenLabs agent to manage customer relationships by using tool calling to step through the CRM process.
Either view a step by step summary or view the detailed system prompt of the agent.

<Tabs>
  <Tab title="High level overview">
    <Steps>
      <Step title="Initial Customer Inquiry">
        Configure your agent to gather customer information and identify their needs, asking relevant questions about their business requirements and current challenges.
      </Step>

      <Step title="Customer Data Lookup">
        Configure the agent to check for existing customer records by:

        * Using the `salesforce_search_records` tool to find existing contacts, accounts, or leads
        * Retrieving customer history and previous interactions
        * Extracting relevant details via the `salesforce_get_record` tool
        * Using this information to personalize the conversation
      </Step>

      <Step title="Lead Qualification">
        If the customer is new or requires follow-up:

        * Collect comprehensive contact information
        * Assess business needs and qualification criteria
        * Determine the appropriate sales process or routing
      </Step>

      <Step title="Record Creation">
        * Use the `salesforce_create_record` tool after information verification
        * Create leads, contacts, or opportunities as appropriate
        * Confirm record creation with the customer
        * Inform them about next steps in the sales process
      </Step>
    </Steps>
  </Tab>

  <Tab title="Detailed system prompt">
    ```text
      # Personality

      You are a helpful sales assistant responsible for managing customer relationships and creating records in Salesforce using the available tools. Be friendly, professional, and consultative in your approach.

      # Environment

      You operate in a sales setting via voice or chat interface, where you engage with potential customers to gather information, check for existing CRM data, and create Salesforce records when necessary.

      # Tone

      Begin by asking about the customer's business needs and current challenges.

      Then, ask relevant qualification questions to understand their requirements, one question at a time, and wait for their response before proceeding.

      Once you have basic information about the customer, say you will check for any existing records in the system.

      Use any existing information to personalize the conversation and avoid asking for data you already have.

      When discussing opportunities, always reference them by name (e.g., "Q1 Enterprise Deal") rather than by ID.

      # Goal

      After checking existing records, qualify the customer by gathering:
      - Company name and size
      - Industry and business type
      - Current challenges and pain points
      - Budget and timeline information
      - Decision-making authority

      Once you have qualified the customer, gather the following contact details:
      - Full name and job title
      - Business email address (ensure it's formatted correctly)
      - Phone number
      - Company name and address

      Read the email back to the customer to confirm accuracy.

      Once all information is confirmed, explain that you will create a record in our system.

      Create the appropriate record (Lead, Contact, or Opportunity) using the `salesforce_create_record` tool.

      Thank the customer and explain the next steps in the sales process.

      # Guardrails

      - Always check for existing records before creating new ones.
      - If the customer asks to proceed, do so with the existing information.
      - Qualify leads appropriately based on their responses.
      - Do not discuss topics outside of business solutions and sales.
      - Always maintain professional communication.
      - Protect customer privacy and handle data securely.

      # Tools

      - Call `salesforce_search_records` to look for existing contacts, accounts, or leads (always include Name fields and human-readable information in your SOQL queries).
      - If found, call `salesforce_get_record` to get detailed information about the existing record.
      - Use `salesforce_create_record` to generate Leads, Contacts, or Opportunities after qualification.
    ```
  </Tab>
</Tabs>

<Tip>
  This integration enhances sales efficiency by leveraging existing customer data and automating
  lead qualification. Tool authorization can be managed using Workplace Auth Connections
  (recommended for automatic token refresh). The tools are configured to return human-readable names
  and descriptions rather than technical IDs to improve conversation quality.
</Tip>

## Authentication Setup

Before configuring the tools, you must set up OAuth 2.0 authentication with Salesforce using an External Client App.

### Step 1: Create an External Client App in Salesforce

1. Log into your Salesforce org as an administrator
2. Go to **Setup** → **App Manager** (or search "App Manager" in Quick Find)
3. Click **New External Client App**
4. Complete the basic information:
   * **External Client App Name**: ElevenLabs Agents
   * **API Name**: ElevenLabs\_Conversational\_AI
   * **Contact Email**: Your administrator email
5. In the **API (Enable OAuth Settings)** section:
   * Check **Enable OAuth Settings**
   * **Callback URL**: `https://api.elevenlabs.io/oauth/callback` (or your specific callback URL)
   * **OAuth Start URL**: `https://api.elevenlabs.io/oauth/start` (required field)
   * **Selected OAuth Scopes**: Add these scopes:
     * **Full access (full)**
     * **Perform requests on your behalf at any time (refresh\_token, offline\_access)**
     * **Manage user data via api**
6. Click **Save**
7. Copy the **Consumer Key** and **Consumer Secret** - you'll need these for authentication

### Step 2: Configure OAuth Client Credentials Flow

<Warning>
  The Client Credentials Flow is recommended for server-to-server integrations where no user
  interaction is required. Ensure your Salesforce admin has enabled this flow.
</Warning>

1. **Enable Client Credentials Flow**:

   * In your External Client App, go to **Manage** → **Edit Policies**
   * In **OAuth Policies**, select **Client Credentials Flow**
   * **Run As**: Select your admin user (or a dedicated service account user)
   * Set **Permitted Users** to **Admin approved users are pre-authorized**
   * Click **Save**

   **Important**: The "Run As" user determines the permissions for all API calls. Choose a user with:

   * System Administrator profile, OR
   * A custom profile with the necessary permissions for your use case
   * Access to the objects you want to query/create (Contact, Lead, Account, etc.)
   * **API Enabled** permission must be checked

2. **Find Your Salesforce Domain**:
   Your Salesforce domain is required for API calls. Here's how to find it:

   **Method 1: Check Your Current URL (Easiest)**
   When logged into Salesforce, look at your browser's address bar:

   * **Lightning Experience**: `https://yourcompany.lightning.force.com/`
   * **My Domain**: `https://yourcompany.my.salesforce.com/`

   **Method 2: Setup → Company Information**

   * Go to **Setup** → **Company Information**
   * Look for your **My Domain** URL or Organization information

   **Method 3: Setup → Domain Management**

   * Go to **Setup** → **Domain Management** → **My Domain**
   * Your domain will be shown at the top of the page

   **Common Domain Formats:**

   * `https://yourcompany.my.salesforce.com` (My Domain)
   * `https://yourcompany.lightning.force.com` (Lightning)
   * `https://yourcompany.develop.my.salesforce.com` (Sandbox)

   **Note**: Use the full domain without trailing slash for API calls.

3. **Setup Complete**: You have now created the External Client App and configured Client Credentials Flow. The Consumer Key and Consumer Secret will be used for token generation in the tool authorization step.

## Tool Configurations

The integration with Salesforce employs three primary webhook tools to manage customer relationships. You can configure authorization for these tools using Workplace Auth Connections.

## Authorization - Workplace OAuth2 Connection

<Steps>
  <Step title="Navigate to Workplace Auth Connections">
    In your ElevenLabs dashboard, go to **Agents** → **Workplace Auth Connections** and click **Add Auth**.
  </Step>

  <Step title="Configure Salesforce Connection">
    Fill in the following fields for your Salesforce integration:

    **Connection Name**: `Salesforce CRM`

    **Client ID**

    * Your Consumer Key from the External Client App
    * Example: `3MVG9JJlvRU3L4pRiOu8pQt5xXB4xGZGm0yW...`

    **Client Secret**

    * Your Consumer Secret from the External Client App
    * Example: `1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF...`

    **Token URL**

    * Your Salesforce domain's OAuth token endpoint
    * Format: `https://your-domain.my.salesforce.com/services/oauth2/token`
    * Example: `https://mycompany.my.salesforce.com/services/oauth2/token`

    **Scopes (optional)**

    * OAuth scopes for Salesforce API access
    * Recommended: `full, api, refresh_token`
    * Leave blank to use default scopes from your External Client App

    **Extra Parameters (JSON)**

    * Additional OAuth parameters specific to your setup
    * Example for Client Credentials flow:

    ```json
    {
      "grant_type": "client_credentials"
    }
    ```
  </Step>

  <Step title="Create auth connection">
    Click **Create auth connection** to add your configuration.
  </Step>

  <Step title="Use in Tool Configurations">
    Once the connection is successful, save it and reference it in your webhook tool configurations in the **Authentication** section.
  </Step>
</Steps>

<Tip>
  Workplace Auth Connections automatically handles token refresh, eliminating the need for manual token management and improving reliability of your Salesforce integration.
</Tip>

### Tool Configurations

Use the tabs below to review each tool's configuration. Remember to add Workplace Auth Connection to the tool (OAuth2).

<Tabs>
  <Tab title="salesforce_search_records">
    **Name:** salesforce\_search\_records
    **Description:** Searches for existing records in Salesforce using SOQL queries. Always returns human-readable information including Names, not just IDs.
    **Method:** GET
    **URL:** `https://your-domain.my.salesforce.com/services/data/v58.0/query/?q={soql_query}`

    **Headers:**

    * **Content-Type:** `application/json`

    **Query Parameters:**

    * **q:** SOQL query string (e.g., "SELECT Id, Name, Email FROM Contact WHERE Email = '[example@email.com](mailto:example@email.com)'")

    **Tool JSON:**

    ```json
    {
      "type": "webhook",
      "name": "salesforce_search_records",
      "description": "Searches for existing records in Salesforce using SOQL queries. Always returns human-readable names and details, not just IDs.",
      "api_schema": {
        "url": "https://your-domain.my.salesforce.com/services/data/v58.0/query/",
        "method": "GET",
        "path_params_schema": [],
        "query_params_schema": [
          {
            "id": "q",
            "type": "string",
            "description": "SOQL query string to search for records. Always include Name fields and other human-readable information. Example: SELECT Id, Name, Email, Phone, Company FROM Contact WHERE Email = 'customer@example.com'. For Opportunities, include: SELECT Id, Name, StageName, Amount, CloseDate, Account.Name FROM Opportunity",
            "dynamic_variable": "",
            "constant_value": "",
            "required": true,
            "value_type": "llm_prompt"
          }
        ],
        "request_body_schema": null,
        "request_headers": [
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 30,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="salesforce_get_record">
    **Name:** salesforce\_get\_record
    **Description:** Retrieves detailed information about a specific Salesforce record.
    **Method:** GET
    **URL:** `https://your-domain.my.salesforce.com/services/data/v58.0/sobjects/{object_type}/{record_id}`

    **Headers:**

    * **Content-Type:** `application/json`

    **Path Parameters:**

    * **object\_type:** The Salesforce object type (Contact, Lead, Account, etc.)
    * **record\_id:** The unique Salesforce record ID

    **Tool JSON:**

    ```json
    {
      "type": "webhook",
      "name": "salesforce_get_record",
      "description": "Retrieves detailed information about a specific Salesforce record.",
      "api_schema": {
        "url": "https://your-domain.my.salesforce.com/services/data/v58.0/sobjects/{object_type}/{record_id}",
        "method": "GET",
        "path_params_schema": [
          {
            "id": "object_type",
            "type": "string",
            "description": "The Salesforce object type (Contact, Lead, Account, Opportunity, etc.)",
            "dynamic_variable": "",
            "constant_value": "",
            "required": true,
            "value_type": "llm_prompt"
          },
          {
            "id": "record_id",
            "type": "string",
            "description": "The unique Salesforce record ID obtained from search results",
            "dynamic_variable": "",
            "constant_value": "",
            "required": true,
            "value_type": "llm_prompt"
          }
        ],
        "query_params_schema": [],
        "request_body_schema": null,
        "request_headers": [
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 30,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>

  <Tab title="salesforce_create_record">
    **Name:** salesforce\_create\_record
    **Description:** Creates a new record in Salesforce.
    **Method:** POST
    **URL:** `https://your-domain.my.salesforce.com/services/data/v58.0/sobjects/{object_type}/`

    **Headers:**

    * **Content-Type:** `application/json`

    **Path Parameters:**

    * **object\_type:** The Salesforce object type to create (Lead, Contact, Account, etc.)

    **Body Parameters:**

    * **Dynamic JSON object** containing the record fields and values

    **Tool JSON:**

    ```json
    {
      "type": "webhook",
      "name": "salesforce_create_record",
      "description": "Creates a new record in Salesforce (Lead, Contact, Account, Opportunity, etc.)",
      "api_schema": {
        "url": "https://your-domain.my.salesforce.com/services/data/v58.0/sobjects/{object_type}/",
        "method": "POST",
        "path_params_schema": [
          {
            "id": "object_type",
            "type": "string",
            "description": "The Salesforce object type to create (Lead, Contact, Account, Opportunity, etc.)",
            "dynamic_variable": "",
            "constant_value": "",
            "required": true,
            "value_type": "llm_prompt"
          }
        ],
        "query_params_schema": [],
        "request_body_schema": {
          "id": "record_data",
          "type": "object",
          "description": "Record data for the new Salesforce record",
          "required": true,
          "properties": [
            {
              "id": "FirstName",
              "type": "string",
              "description": "First name of the contact or lead",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            },
            {
              "id": "LastName",
              "type": "string",
              "description": "Last name of the contact or lead",
              "dynamic_variable": "",
              "constant_value": "",
              "required": true,
              "value_type": "llm_prompt"
            },
            {
              "id": "Email",
              "type": "string",
              "description": "Email address. Must be properly formatted: user@domain.com",
              "dynamic_variable": "",
              "constant_value": "",
              "required": true,
              "value_type": "llm_prompt"
            },
            {
              "id": "Phone",
              "type": "string",
              "description": "Phone number of the contact or lead",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            },
            {
              "id": "Company",
              "type": "string",
              "description": "Company name (required for Lead object)",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            },
            {
              "id": "Title",
              "type": "string",
              "description": "Job title of the contact or lead",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            },
            {
              "id": "Industry",
              "type": "string",
              "description": "Industry of the lead's company",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            },
            {
              "id": "Description",
              "type": "string",
              "description": "Additional notes or description about the lead/contact",
              "dynamic_variable": "",
              "constant_value": "",
              "required": false,
              "value_type": "llm_prompt"
            }
          ]
        },
        "request_headers": [
          {
            "type": "value",
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      },
      "response_timeout_secs": 30,
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      }
    }
    ```
  </Tab>
</Tabs>

## Common SOQL Queries

Here are some commonly used SOQL queries for the `salesforce_search_records` tool. It can be useful to consider this structure when customizing system/tool prompt. All queries prioritize human-readable information over technical IDs:

### Search for Contacts by Email

```sql
SELECT Id, Name, Email, Phone, Title, Account.Name, Account.Type FROM Contact WHERE Email = 'customer@example.com'
```

### Search for Leads by Email or Phone

```sql
SELECT Id, Name, Email, Phone, Company, Industry, Status, LeadSource, Title FROM Lead WHERE Email = 'customer@example.com' OR Phone = '+1234567890'
```

### Search for Accounts by Name

```sql
SELECT Id, Name, Type, Industry, Phone, BillingCity, BillingState, Website FROM Account WHERE Name LIKE '%Company Name%'
```

### Search for Recent Opportunities

```sql
SELECT Id, Name, StageName, Amount, CloseDate, Account.Name, Account.Type, Owner.Name, Description FROM Opportunity WHERE CreatedDate = THIS_MONTH
```

### Search for Opportunities by Account

```sql
SELECT Id, Name, StageName, Amount, CloseDate, Probability, NextStep, Owner.Name FROM Opportunity WHERE Account.Name LIKE '%Company Name%'
```

## Integration Testing

<Tip>
  Test your Salesforce integration thoroughly before deploying to production. The following steps
  will help you validate that all components are working correctly.
</Tip>

### Testing Your Integration

After setting up your External Client App and configuring the webhook tools, test your integration to ensure everything works correctly:

### Agent Testing

Test your integration with your ElevenLabs agent:

1. **Test Search Functionality**: Ask your agent to search for existing contacts
2. **Test Record Creation**: Have your agent create a new lead or contact
3. **Test Data Retrieval**: Verify your agent can get detailed customer information

## Impact

With this integration in place, you can:

* **Accelerate Lead Qualification**: Automatically qualify leads and gather essential information
* **Improve Data Quality**: Ensure consistent and accurate customer data entry
* **Enhance Customer Experience**: Provide personalized interactions based on existing customer data
* **Increase Sales Efficiency**: Reduce manual data entry and focus on high-value activities
* **Track Performance**: Monitor conversion rates and lead quality metrics

## Security Considerations

* Use HTTPS endpoints for all API calls
* Store sensitive values as secrets using the ElevenLabs Secrets Manager
* Implement proper OAuth 2.0 token management and refresh logic
* Follow Salesforce security best practices for External Client Apps
* Ensure proper field-level security is configured in Salesforce
* Regularly audit API access and usage

## Common Salesforce Objects

| Object          | Purpose                                        | Common Fields                                                |
| --------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| **Lead**        | Potential customers not yet qualified          | FirstName, LastName, Email, Phone, Company, Industry, Status |
| **Contact**     | Qualified individuals associated with accounts | FirstName, LastName, Email, Phone, AccountId, Title          |
| **Account**     | Organizations or companies                     | Name, Type, Industry, Phone, BillingAddress                  |
| **Opportunity** | Sales deals in progress                        | Name, StageName, Amount, CloseDate, AccountId                |
| **Case**        | Customer service requests                      | Subject, Description, Status, Priority, ContactId            |

## Conclusion

This guide details how to integrate Salesforce into our ElevenAgents for comprehensive customer relationship management. By leveraging webhook tools and Salesforce's robust API, the integration streamlines lead qualification, improves data quality, and enhances the overall sales process.

For additional details on tool configuration or other integrations, refer to the [Tools Overview](/docs/agents-platform/customization/tools/server-tools).

## Additional Resources

* [Salesforce REST API Documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/)
* [SOQL Query Language Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/)
* [External Client Apps and OAuth 2.0](https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm)
* [Salesforce Security Best Practices](https://help.salesforce.com/s/articleView?id=sf.security_overview.htm)


# Agent WebSockets

GET /v1/convai/conversation

Establish a WebSocket connection for real-time conversations with an AI agent.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/eleven-agents/websocket

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: V 1 Convai Conversation
  version: subpackage_v1ConvaiConversation.v1ConvaiConversation
  description: >-
    Establish a WebSocket connection for real-time conversations with an AI
    agent.
channels:
  /v1/convai/conversation:
    description: >-
      Establish a WebSocket connection for real-time conversations with an AI
      agent.
    bindings:
      ws:
        query:
          type: object
          properties:
            agent_id:
              description: Any type
    publish:
      operationId: v-1-convai-conversation-publish
      summary: subscribe
      description: >-
        Defines the message types that can be received by the client from the
        server
      message:
        name: subscribe
        title: subscribe
        description: >-
          Defines the message types that can be received by the client from the
          server
        payload:
          $ref: '#/components/schemas/V1ConvaiConversationSubscribe'
    subscribe:
      operationId: v-1-convai-conversation-subscribe
      summary: publish
      description: Defines the message types that can be sent from client to server
      message:
        name: publish
        title: publish
        description: Defines the message types that can be sent from client to server
        payload:
          $ref: '#/components/schemas/V1ConvaiConversationPublish'
servers:
  Production:
    url: wss://api.elevenlabs.io/
    protocol: wss
    x-default: true
  Production-US:
    url: wss://api.us.elevenlabs.io/
    protocol: wss
  Production-EU:
    url: wss://api.eu.residency.elevenlabs.io/
    protocol: wss
  Production-India:
    url: wss://api.in.residency.elevenlabs.io/
    protocol: wss
components:
  schemas:
    ConversationInitiationMetadataConversationInitiationMetadataEvent:
      type: object
      properties:
        conversation_id:
          type: string
          description: Unique identifier for the conversation session.
        agent_output_audio_format:
          type: string
          description: Audio format specification for agent's speech output.
        user_input_audio_format:
          type: string
          description: Audio format specification for user's speech input.
    ConversationInitiationMetadata:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: conversation_initiation_metadata
        conversation_initiation_metadata_event:
          $ref: >-
            #/components/schemas/ConversationInitiationMetadataConversationInitiationMetadataEvent
          description: Initial conversation metadata
    UserTranscriptUserTranscriptionEvent:
      type: object
      properties:
        user_transcript:
          type: string
          description: Transcribed text from user's speech input.
    UserTranscript:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: user_transcript
        user_transcription_event:
          $ref: '#/components/schemas/UserTranscriptUserTranscriptionEvent'
          description: Transcription event data
    AgentResponseAgentResponseEvent:
      type: object
      properties:
        agent_response:
          type: string
          description: Text content of the agent's response.
      required:
        - agent_response
    AgentResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: agent_response
        agent_response_event:
          $ref: '#/components/schemas/AgentResponseAgentResponseEvent'
          description: Agent response event data
      required:
        - type
    AgentResponseCorrectionAgentResponseCorrectionEvent:
      type: object
      properties:
        original_agent_response:
          type: string
          description: The original agent response before correction
        corrected_agent_response:
          type: string
          description: The corrected agent response after truncation or interruption
      required:
        - original_agent_response
        - corrected_agent_response
    AgentResponseCorrection:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: agent_response_correction
        agent_response_correction_event:
          $ref: >-
            #/components/schemas/AgentResponseCorrectionAgentResponseCorrectionEvent
          description: Agent response correction event data
      required:
        - type
    AudioResponseAudioEvent:
      type: object
      properties:
        audio_base_64:
          type: string
          description: Base64-encoded audio data of agent's speech.
        event_id:
          type: integer
          description: Sequential identifier for this audio event.
    AudioResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: audio
        audio_event:
          $ref: '#/components/schemas/AudioResponseAudioEvent'
          description: Audio event data
      required:
        - type
    InterruptionInterruptionEvent:
      type: object
      properties:
        event_id:
          type: integer
          description: ID of the event that was interrupted.
    Interruption:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: interruption
        interruption_event:
          $ref: '#/components/schemas/InterruptionInterruptionEvent'
          description: Interruption event data
      required:
        - type
    PingPingEvent:
      type: object
      properties:
        event_id:
          type: integer
          description: Unique identifier for the ping event.
        ping_ms:
          type: integer
          description: Measured round-trip latency in milliseconds.
    Ping:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: ping
        ping_event:
          $ref: '#/components/schemas/PingPingEvent'
          description: Ping event data
      required:
        - type
    ClientToolCallClientToolCall:
      type: object
      properties:
        tool_name:
          type: string
          description: Identifier of the tool to be executed.
        tool_call_id:
          type: string
          description: Unique identifier for this tool call request.
        parameters:
          type: object
          additionalProperties:
            description: Any type
          description: Tool-specific parameters for the execution request.
    ClientToolCall:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: client_tool_call
        client_tool_call:
          $ref: '#/components/schemas/ClientToolCallClientToolCall'
          description: Tool call request data
      required:
        - type
    ContextualUpdate:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: contextual_update
        text:
          type: string
          description: Contextual information to be added to the conversation state.
      required:
        - type
        - text
    VadScoreVadScoreEvent:
      type: object
      properties:
        vad_score:
          type: number
          format: double
          description: Voice activity detection confidence score between 0 and 1
      required:
        - vad_score
    VadScore:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: vad_score
        vad_score_event:
          $ref: '#/components/schemas/VadScoreVadScoreEvent'
          description: VAD event data
      required:
        - type
    InternalTentativeAgentResponseTentativeAgentResponseInternalEvent:
      type: object
      properties:
        tentative_agent_response:
          type: string
          description: Preliminary text from the agent
      required:
        - tentative_agent_response
    InternalTentativeAgentResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: internal_tentative_agent_response
        tentative_agent_response_internal_event:
          $ref: >-
            #/components/schemas/InternalTentativeAgentResponseTentativeAgentResponseInternalEvent
          description: Preliminary event data containing agent's tentative response
      required:
        - type
    V1ConvaiConversationSubscribe:
      oneOf:
        - $ref: '#/components/schemas/ConversationInitiationMetadata'
        - $ref: '#/components/schemas/UserTranscript'
        - $ref: '#/components/schemas/AgentResponse'
        - $ref: '#/components/schemas/AgentResponseCorrection'
        - $ref: '#/components/schemas/AudioResponse'
        - $ref: '#/components/schemas/Interruption'
        - $ref: '#/components/schemas/Ping'
        - $ref: '#/components/schemas/ClientToolCall'
        - $ref: '#/components/schemas/ContextualUpdate'
        - $ref: '#/components/schemas/VadScore'
        - $ref: '#/components/schemas/InternalTentativeAgentResponse'
    UserAudioChunk:
      type: object
      properties:
        user_audio_chunk:
          type: string
          description: Base64-encoded audio data chunk from user input.
    Pong:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: pong
        event_id:
          type: integer
          description: The ID of the ping event being responded to.
      required:
        - type
    ConversationInitiationClientDataConversationConfigOverrideAgentPrompt:
      type: object
      properties:
        prompt:
          type: string
          description: Custom system prompt to guide agent behavior.
        llm:
          type: string
          description: The LLM to query with the prompt and the chat history.
    ConversationInitiationClientDataConversationConfigOverrideAgent:
      type: object
      properties:
        prompt:
          $ref: >-
            #/components/schemas/ConversationInitiationClientDataConversationConfigOverrideAgentPrompt
          description: System prompt configuration
        first_message:
          type: string
          description: Initial message the agent should use to start the conversation.
        language:
          type: string
          description: Preferred language code for the conversation.
    ConversationInitiationClientDataConversationConfigOverrideTts:
      type: object
      properties:
        voice_id:
          type: string
          description: ID of the voice to use for text-to-speech synthesis.
        speed:
          type: number
          format: double
          description: The speed of generated speech, between 0.7 and 1.2.
        stability:
          type: number
          format: double
          description: The stability of generated speech, between 0.0 and 1.0.
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech, between 0.0 and 1.0.
    ConversationInitiationClientDataConversationConfigOverride:
      type: object
      properties:
        agent:
          $ref: >-
            #/components/schemas/ConversationInitiationClientDataConversationConfigOverrideAgent
          description: Configuration for the AI agent's behavior
        tts:
          $ref: >-
            #/components/schemas/ConversationInitiationClientDataConversationConfigOverrideTts
          description: Text-to-speech configuration
    ConversationInitiationClientDataCustomLlmExtraBody:
      type: object
      properties:
        temperature:
          type: number
          format: double
          description: Temperature parameter controlling response randomness.
        max_tokens:
          type: integer
          description: Maximum number of tokens allowed in LLM responses.
    ConversationInitiationClientDataDynamicVariables:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    ConversationInitiationClientData:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: conversation_initiation_client_data
        conversation_config_override:
          $ref: >-
            #/components/schemas/ConversationInitiationClientDataConversationConfigOverride
          description: Override settings for conversation behavior
        custom_llm_extra_body:
          $ref: >-
            #/components/schemas/ConversationInitiationClientDataCustomLlmExtraBody
          description: Additional LLM configuration parameters
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/ConversationInitiationClientDataDynamicVariables
          description: >-
            Dictionary of dynamic variables to be used in the conversation. Keys
            are the dynamic variable names which must be strings, values can be
            strings, numbers, integers, or booleans.
      required:
        - type
    ClientToolResult:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: client_tool_result
        tool_call_id:
          type: string
          description: Unique identifier of the tool call being responded to.
        result:
          type: string
          description: Result data from the tool execution.
        is_error:
          type: boolean
          description: Flag indicating if the tool execution encountered an error.
      required:
        - type
    UserMessage:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: user_message
        text:
          type: string
          description: Text message content from the user.
      required:
        - type
    UserActivity:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: user_activity
      required:
        - type
    V1ConvaiConversationPublish:
      oneOf:
        - $ref: '#/components/schemas/UserAudioChunk'
        - $ref: '#/components/schemas/Pong'
        - $ref: '#/components/schemas/ConversationInitiationClientData'
        - $ref: '#/components/schemas/ClientToolResult'
        - $ref: '#/components/schemas/ContextualUpdate'
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/UserActivity'

```

# List agent branches

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches

Returns a list of branches an agent has

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Agent Branches
  version: endpoint_conversationalAi/agents/branches.list
paths:
  /v1/convai/agents/{agent_id}/branches:
    get:
      operationId: list
      summary: List Agent Branches
      description: Returns a list of branches an agent has
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: include_archived
          in: query
          description: Whether archived branches should be included
          required: false
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: How many results at most should be returned
          required: false
          schema:
            type: integer
            default: 100
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ListResponseAgentBranchSummary'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ListResponseMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        draft_exists:
          type: boolean
          default: false
          description: Whether a draft exists for the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived
    type_:ListResponseAgentBranchSummary:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/type_:ListResponseMeta'
        results:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentBranchSummary'
      required:
        - results

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.list("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        includeArchived: true,
        limit: 1,
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.list(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    include_archived=True,
    limit=1
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create agent branch

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches
Content-Type: application/json

Create a new branch from a given version of main branch

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create A New Branch
  version: endpoint_conversationalAi/agents/branches.create
paths:
  /v1/convai/agents/{agent_id}/branches:
    post:
      operationId: create
      summary: Create A New Branch
      description: Create a new branch from a given version of main branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreateAgentBranchResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_version_id:
                  type: string
                  description: ID of the version to branch from
                name:
                  type: string
                  description: Name of the branch. It is unique within the agent.
                description:
                  type: string
                  description: Description for the branch
                conversation_config:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Changes to apply to conversation config
                platform_settings:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Changes to apply to platform settings
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: Updated workflow definition
              required:
                - parent_version_id
                - name
                - description
components:
  schemas:
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: default
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: disabled
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: override
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:CreateAgentBranchResponseModel:
      type: object
      properties:
        created_branch_id:
          type: string
          description: ID of the created branch
        created_version_id:
          type: string
          description: ID of the first version on the created branch
      required:
        - created_branch_id
        - created_version_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        parentVersionId: "parent_version_id",
        name: "name",
        description: "description",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    parent_version_id="parent_version_id",
    name="name",
    description="description"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches"

	payload := strings.NewReader("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches', [
  'body' => '{
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get agent branch

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}

Get information about a single agent branch

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Branch
  version: endpoint_conversationalAi/agents/branches.get
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    get:
      operationId: get
      summary: Get Agent Branch
      description: Get information about a single agent branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          description: Unique identifier for the branch.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentBranchResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchBasicInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    type_:AgentVersionParents:
      type: object
      properties:
        in_branch_parent_id:
          type: string
        out_of_branch_parent_id:
          type: string
        merged_into_branch_id:
          type: string
        merged_from_branch_id:
          type: string
    type_:AgentVersionMetadata:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        version_description:
          type: string
        seq_no_in_branch:
          type: integer
        time_committed_secs:
          type: integer
        parents:
          $ref: '#/components/schemas/type_:AgentVersionParents'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
      required:
        - id
        - agent_id
        - branch_id
        - version_description
        - seq_no_in_branch
        - time_committed_secs
        - parents
    type_:AgentBranchResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        parent_branch:
          $ref: '#/components/schemas/type_:AgentBranchBasicInfo'
          description: Parent branch of the branch
        most_recent_versions:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentVersionMetadata'
          description: Most recent versions on the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update agent branch

PATCH https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}
Content-Type: application/json

Update agent branch properties such as archiving status and protection level

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Agent Branch
  version: endpoint_conversationalAi/agents/branches.update
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    patch:
      operationId: update
      summary: Update Agent Branch
      description: >-
        Update agent branch properties such as archiving status and protection
        level
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          description: Unique identifier for the branch.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentBranchResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New name for the branch. Must be unique within the agent.
                is_archived:
                  type: boolean
                  description: Whether the branch should be archived
                protection_status:
                  $ref: '#/components/schemas/type_:BranchProtectionStatus'
                  description: The protection level for the branch
components:
  schemas:
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchBasicInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    type_:AgentVersionParents:
      type: object
      properties:
        in_branch_parent_id:
          type: string
        out_of_branch_parent_id:
          type: string
        merged_into_branch_id:
          type: string
        merged_from_branch_id:
          type: string
    type_:AgentVersionMetadata:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        version_description:
          type: string
        seq_no_in_branch:
          type: integer
        time_committed_secs:
          type: integer
        parents:
          $ref: '#/components/schemas/type_:AgentVersionParents'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
      required:
        - id
        - agent_id
        - branch_id
        - version_description
        - seq_no_in_branch
        - time_committed_secs
        - parents
    type_:AgentBranchResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        parent_branch:
          $ref: '#/components/schemas/type_:AgentBranchBasicInfo'
          description: Parent branch of the branch
        most_recent_versions:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentVersionMetadata'
          description: Most recent versions on the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.update("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.update(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete agent branch

DELETE https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete V 1 Convai Agents Agent Id Branches Branch Id
  version: endpoint_.deleteV1ConvaiAgentsAgentIdBranchesBranchId
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    delete:
      operationId: delete-v-1-convai-agents-agent-id-branches-branch-id
      summary: Delete V 1 Convai Agents Agent Id Branches Branch Id
      tags:
        - []
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.deleteV1ConvaiAgentsAgentIdBranchesBranchId("agent_id", "branch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.delete_v_1_convai_agents_agent_id_branches_branch_id(
    agent_id="agent_id",
    branch_id="branch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Merge agent branch

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge
Content-Type: application/json

Merge a branch into a target branch

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/merge

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Merge A Branch Into A Target Branch
  version: endpoint_conversationalAi/agents/branches.merge
paths:
  /v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge:
    post:
      operationId: merge
      summary: Merge A Branch Into A Target Branch
      description: Merge a branch into a target branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: source_branch_id
          in: path
          description: Unique identifier for the source branch to merge from.
          required: true
          schema:
            type: string
        - name: target_branch_id
          in: query
          description: The ID of the target branch to merge into (must be the main branch).
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                archive_source_branch:
                  type: boolean
                  default: true
                  description: Whether to archive the source branch after merging

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.merge("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbrch_8901k4t9z5defmb8vh3e9361y7nj", {
        targetBranchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.merge(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    source_branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    target_branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create deployment

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/deployments
Content-Type: application/json

Create a new deployment for an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/deployments/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Or Update Deployments
  version: endpoint_conversationalAi/agents/deployments.create
paths:
  /v1/convai/agents/{agent_id}/deployments:
    post:
      operationId: create
      summary: Create Or Update Deployments
      description: Create a new deployment for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/deployments
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentDeploymentResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                deployment_request:
                  $ref: '#/components/schemas/type_:AgentDeploymentRequest'
                  description: Request to create a new deployment
              required:
                - deployment_request
components:
  schemas:
    type_:AgentDeploymentPercentageStrategy:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: percentage
        traffic_percentage:
          type: number
          format: double
          description: Traffic percentage to deploy
      required:
        - traffic_percentage
    type_:AgentDeploymentRequestItem:
      type: object
      properties:
        branch_id:
          type: string
          description: ID of the branch to deploy
        deployment_strategy:
          $ref: '#/components/schemas/type_:AgentDeploymentPercentageStrategy'
      required:
        - branch_id
        - deployment_strategy
    type_:AgentDeploymentRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentDeploymentRequestItem'
          description: List of deployment requests
      required:
        - requests
    type_:AgentDeploymentResponse:
      type: object
      properties:
        traffic_percentage_branch_id_map:
          type: object
          additionalProperties:
            type: number
            format: double
          description: Map of branch IDs to traffic percentages

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.deployments.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        deploymentRequest: {
            requests: [
                {
                    branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
                    deploymentStrategy: {
                        trafficPercentage: 0.5,
                        type: "percentage",
                    },
                },
            ],
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.deployments.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    deployment_request={
        "requests": [
            {
                "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
                "deployment_strategy": {
                    "traffic_percentage": 0.5,
                    "type": "percentage"
                }
            }
        ]
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments"

	payload := strings.NewReader("{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")
  .header("Content-Type", "application/json")
  .body("{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments', [
  'body' => '{
  "deployment_request": {
    "requests": [
      {
        "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
        "deployment_strategy": {
          "traffic_percentage": 0.5,
          "type": "percentage"
        }
      }
    ]
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["deployment_request": ["requests": [
      [
        "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
        "deployment_strategy": [
          "traffic_percentage": 0.5,
          "type": "percentage"
        ]
      ]
    ]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create draft

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/drafts
Content-Type: application/json

Create a new draft for an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/drafts/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Agent Draft
  version: endpoint_conversationalAi/agents/drafts.create
paths:
  /v1/convai/agents/{agent_id}/drafts:
    post:
      operationId: create
      summary: Create Agent Draft
      description: Create a new draft for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/drafts
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: query
          description: The ID of the agent branch to use
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_config:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Conversation config for the draft
                platform_settings:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Platform settings for the draft
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: Workflow for the draft
                name:
                  type: string
                  description: Name for the draft
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags to help classify and filter the agent
              required:
                - conversation_config
                - platform_settings
                - workflow
                - name
components:
  schemas:
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: default
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: disabled
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: override
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.drafts.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
        conversationConfig: {
            "key": "value",
        },
        platformSettings: {
            "key": "value",
        },
        workflow: {
            edges: {
                "entry_to_tool_a": {
                    source: "entry_node",
                    target: "tool_node_a",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "start_to_entry": {
                    source: "start_node",
                    target: "entry_node",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_a_to_failure": {
                    source: "tool_node_a",
                    target: "failure_node",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_a_to_tool_b": {
                    source: "tool_node_a",
                    target: "tool_node_b",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_b_to_agent_transfer": {
                    source: "tool_node_b",
                    target: "success_transfer",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_b_to_conversation": {
                    source: "tool_node_b",
                    target: "success_conversation",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_b_to_end": {
                    source: "tool_node_b",
                    target: "success_end",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
                "tool_b_to_phone": {
                    source: "tool_node_b",
                    target: "success_phone",
                    forwardCondition: {
                        type: "expression",
                        expression: {
                            type: "and_operator",
                            children: [
                                {
                                    type: "boolean_literal",
                                    value: true,
                                },
                            ],
                        },
                    },
                },
            },
            nodes: {
                "entry_node": {
                    type: "end",
                },
                "failure_node": {
                    type: "end",
                },
                "start_node": {
                    type: "end",
                },
                "success_conversation": {
                    type: "end",
                },
                "success_end": {
                    type: "end",
                },
                "success_phone": {
                    type: "end",
                },
                "success_transfer": {
                    type: "end",
                },
                "tool_node_a": {
                    type: "end",
                },
                "tool_node_b": {
                    type: "end",
                },
            },
        },
        name: "name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.drafts.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    conversation_config={
        "key": "value"
    },
    platform_settings={
        "key": "value"
    },
    workflow={
        "edges": {
            "entry_to_tool_a": {
                "source": "entry_node",
                "target": "tool_node_a",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "start_to_entry": {
                "source": "start_node",
                "target": "entry_node",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_a_to_failure": {
                "source": "tool_node_a",
                "target": "failure_node",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_a_to_tool_b": {
                "source": "tool_node_a",
                "target": "tool_node_b",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_b_to_agent_transfer": {
                "source": "tool_node_b",
                "target": "success_transfer",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_b_to_conversation": {
                "source": "tool_node_b",
                "target": "success_conversation",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_b_to_end": {
                "source": "tool_node_b",
                "target": "success_end",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            },
            "tool_b_to_phone": {
                "source": "tool_node_b",
                "target": "success_phone",
                "forward_condition": {
                    "type": "expression",
                    "expression": {
                        "type": "and_operator",
                        "children": [
                            {
                                "type": "boolean_literal",
                                "value": True
                            }
                        ]
                    }
                }
            }
        },
        "nodes": {
            "entry_node": {
                "type": "end"
            },
            "failure_node": {
                "type": "end"
            },
            "start_node": {
                "type": "end"
            },
            "success_conversation": {
                "type": "end"
            },
            "success_end": {
                "type": "end"
            },
            "success_phone": {
                "type": "end"
            },
            "success_transfer": {
                "type": "end"
            },
            "tool_node_a": {
                "type": "end"
            },
            "tool_node_b": {
                "type": "end"
            }
        }
    },
    name="name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj"

	payload := strings.NewReader("{\n  \"conversation_config\": {\n    \"key\": \"value\"\n  },\n  \"platform_settings\": {\n    \"key\": \"value\"\n  },\n  \"workflow\": {\n    \"edges\": {\n      \"entry_to_tool_a\": {\n        \"source\": \"entry_node\",\n        \"target\": \"tool_node_a\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"start_to_entry\": {\n        \"source\": \"start_node\",\n        \"target\": \"entry_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_failure\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"failure_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_tool_b\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"tool_node_b\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_agent_transfer\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_transfer\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_conversation\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_conversation\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_end\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_end\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_phone\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_phone\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      }\n    },\n    \"nodes\": {\n      \"entry_node\": {\n        \"type\": \"end\"\n      },\n      \"failure_node\": {\n        \"type\": \"end\"\n      },\n      \"start_node\": {\n        \"type\": \"end\"\n      },\n      \"success_conversation\": {\n        \"type\": \"end\"\n      },\n      \"success_end\": {\n        \"type\": \"end\"\n      },\n      \"success_phone\": {\n        \"type\": \"end\"\n      },\n      \"success_transfer\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_a\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_b\": {\n        \"type\": \"end\"\n      }\n    }\n  },\n  \"name\": \"name\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"conversation_config\": {\n    \"key\": \"value\"\n  },\n  \"platform_settings\": {\n    \"key\": \"value\"\n  },\n  \"workflow\": {\n    \"edges\": {\n      \"entry_to_tool_a\": {\n        \"source\": \"entry_node\",\n        \"target\": \"tool_node_a\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"start_to_entry\": {\n        \"source\": \"start_node\",\n        \"target\": \"entry_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_failure\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"failure_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_tool_b\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"tool_node_b\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_agent_transfer\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_transfer\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_conversation\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_conversation\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_end\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_end\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_phone\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_phone\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      }\n    },\n    \"nodes\": {\n      \"entry_node\": {\n        \"type\": \"end\"\n      },\n      \"failure_node\": {\n        \"type\": \"end\"\n      },\n      \"start_node\": {\n        \"type\": \"end\"\n      },\n      \"success_conversation\": {\n        \"type\": \"end\"\n      },\n      \"success_end\": {\n        \"type\": \"end\"\n      },\n      \"success_phone\": {\n        \"type\": \"end\"\n      },\n      \"success_transfer\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_a\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_b\": {\n        \"type\": \"end\"\n      }\n    }\n  },\n  \"name\": \"name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")
  .header("Content-Type", "application/json")
  .body("{\n  \"conversation_config\": {\n    \"key\": \"value\"\n  },\n  \"platform_settings\": {\n    \"key\": \"value\"\n  },\n  \"workflow\": {\n    \"edges\": {\n      \"entry_to_tool_a\": {\n        \"source\": \"entry_node\",\n        \"target\": \"tool_node_a\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"start_to_entry\": {\n        \"source\": \"start_node\",\n        \"target\": \"entry_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_failure\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"failure_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_tool_b\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"tool_node_b\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_agent_transfer\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_transfer\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_conversation\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_conversation\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_end\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_end\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_phone\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_phone\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      }\n    },\n    \"nodes\": {\n      \"entry_node\": {\n        \"type\": \"end\"\n      },\n      \"failure_node\": {\n        \"type\": \"end\"\n      },\n      \"start_node\": {\n        \"type\": \"end\"\n      },\n      \"success_conversation\": {\n        \"type\": \"end\"\n      },\n      \"success_end\": {\n        \"type\": \"end\"\n      },\n      \"success_phone\": {\n        \"type\": \"end\"\n      },\n      \"success_transfer\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_a\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_b\": {\n        \"type\": \"end\"\n      }\n    }\n  },\n  \"name\": \"name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj', [
  'body' => '{
  "conversation_config": {
    "key": "value"
  },
  "platform_settings": {
    "key": "value"
  },
  "workflow": {
    "edges": {
      "entry_to_tool_a": {
        "source": "entry_node",
        "target": "tool_node_a",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "start_to_entry": {
        "source": "start_node",
        "target": "entry_node",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_a_to_failure": {
        "source": "tool_node_a",
        "target": "failure_node",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_a_to_tool_b": {
        "source": "tool_node_a",
        "target": "tool_node_b",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_b_to_agent_transfer": {
        "source": "tool_node_b",
        "target": "success_transfer",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_b_to_conversation": {
        "source": "tool_node_b",
        "target": "success_conversation",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_b_to_end": {
        "source": "tool_node_b",
        "target": "success_end",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      },
      "tool_b_to_phone": {
        "source": "tool_node_b",
        "target": "success_phone",
        "forward_condition": {
          "type": "expression",
          "expression": {
            "type": "and_operator",
            "children": [
              {
                "type": "boolean_literal",
                "value": true
              }
            ]
          }
        }
      }
    },
    "nodes": {
      "entry_node": {
        "type": "end"
      },
      "failure_node": {
        "type": "end"
      },
      "start_node": {
        "type": "end"
      },
      "success_conversation": {
        "type": "end"
      },
      "success_end": {
        "type": "end"
      },
      "success_phone": {
        "type": "end"
      },
      "success_transfer": {
        "type": "end"
      },
      "tool_node_a": {
        "type": "end"
      },
      "tool_node_b": {
        "type": "end"
      }
    }
  },
  "name": "name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"conversation_config\": {\n    \"key\": \"value\"\n  },\n  \"platform_settings\": {\n    \"key\": \"value\"\n  },\n  \"workflow\": {\n    \"edges\": {\n      \"entry_to_tool_a\": {\n        \"source\": \"entry_node\",\n        \"target\": \"tool_node_a\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"start_to_entry\": {\n        \"source\": \"start_node\",\n        \"target\": \"entry_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_failure\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"failure_node\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_a_to_tool_b\": {\n        \"source\": \"tool_node_a\",\n        \"target\": \"tool_node_b\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_agent_transfer\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_transfer\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_conversation\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_conversation\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_end\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_end\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      },\n      \"tool_b_to_phone\": {\n        \"source\": \"tool_node_b\",\n        \"target\": \"success_phone\",\n        \"forward_condition\": {\n          \"type\": \"expression\",\n          \"expression\": {\n            \"type\": \"and_operator\",\n            \"children\": [\n              {\n                \"type\": \"boolean_literal\",\n                \"value\": true\n              }\n            ]\n          }\n        }\n      }\n    },\n    \"nodes\": {\n      \"entry_node\": {\n        \"type\": \"end\"\n      },\n      \"failure_node\": {\n        \"type\": \"end\"\n      },\n      \"start_node\": {\n        \"type\": \"end\"\n      },\n      \"success_conversation\": {\n        \"type\": \"end\"\n      },\n      \"success_end\": {\n        \"type\": \"end\"\n      },\n      \"success_phone\": {\n        \"type\": \"end\"\n      },\n      \"success_transfer\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_a\": {\n        \"type\": \"end\"\n      },\n      \"tool_node_b\": {\n        \"type\": \"end\"\n      }\n    }\n  },\n  \"name\": \"name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "conversation_config": ["key": "value"],
  "platform_settings": ["key": "value"],
  "workflow": [
    "edges": [
      "entry_to_tool_a": [
        "source": "entry_node",
        "target": "tool_node_a",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "start_to_entry": [
        "source": "start_node",
        "target": "entry_node",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_a_to_failure": [
        "source": "tool_node_a",
        "target": "failure_node",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_a_to_tool_b": [
        "source": "tool_node_a",
        "target": "tool_node_b",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_b_to_agent_transfer": [
        "source": "tool_node_b",
        "target": "success_transfer",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_b_to_conversation": [
        "source": "tool_node_b",
        "target": "success_conversation",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_b_to_end": [
        "source": "tool_node_b",
        "target": "success_end",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ],
      "tool_b_to_phone": [
        "source": "tool_node_b",
        "target": "success_phone",
        "forward_condition": [
          "type": "expression",
          "expression": [
            "type": "and_operator",
            "children": [
              [
                "type": "boolean_literal",
                "value": true
              ]
            ]
          ]
        ]
      ]
    ],
    "nodes": [
      "entry_node": ["type": "end"],
      "failure_node": ["type": "end"],
      "start_node": ["type": "end"],
      "success_conversation": ["type": "end"],
      "success_end": ["type": "end"],
      "success_phone": ["type": "end"],
      "success_transfer": ["type": "end"],
      "tool_node_a": ["type": "end"],
      "tool_node_b": ["type": "end"]
    ]
  ],
  "name": "name"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete draft

DELETE https://api.elevenlabs.io/v1/convai/agents/{agent_id}/drafts

Delete a draft for an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/drafts/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Agent Draft
  version: endpoint_conversationalAi/agents/drafts.delete
paths:
  /v1/convai/agents/{agent_id}/drafts:
    delete:
      operationId: delete
      summary: Delete Agent Draft
      description: Delete a draft for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/drafts
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: query
          description: The ID of the agent branch to use
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.drafts.delete("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.drafts.delete(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/drafts?branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create agent

POST https://api.elevenlabs.io/v1/convai/agents/create
Content-Type: application/json

Create an agent from a config object

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create agent
  version: endpoint_conversationalAi/agents.create
paths:
  /v1/convai/agents/create:
    post:
      operationId: create
      summary: Create agent
      description: Create an agent from a config object
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreateAgentResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_config:
                  $ref: '#/components/schemas/type_:ConversationalConfig'
                  description: Conversation configuration for an agent
                platform_settings:
                  $ref: '#/components/schemas/type_:AgentPlatformSettingsRequestModel'
                  description: >-
                    Platform settings for the agent are all settings that aren't
                    related to the conversation orchestration and content.
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: >-
                    Workflow for the agent. This is used to define the flow of
                    the conversation and how the agent interacts with tools.
                name:
                  type: string
                  description: A name to make the agent easier to find
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags to help classify and filter the agent
              required:
                - conversation_config
components:
  schemas:
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfig:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfig:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          default: -1
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          default: Hhmmmm...yeah.
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          default: false
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfig:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          default: 7
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          default: -1
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfig'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          default: false
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          default: cjVigY5qzO86Huf0OWal
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          default: 0.5
          description: The stability of generated speech
        speed:
          type: number
          format: double
          default: 1
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          default: 0.8
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          default: 600
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          default: false
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetOutput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfig:
      type: object
      properties: {}
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ConversationalConfig:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfig'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfig'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOutput'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfig'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfig'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfig'
          description: Agent specific configuration
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:EvaluationSettings:
      type: object
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
          description: Individual criteria that the agent should be evaluated against
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigOutputAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetTermsTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:WidgetLanguagePreset:
      type: object
      properties:
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
        terms_translation:
          $ref: '#/components/schemas/type_:WidgetTermsTranslation'
          description: The translation cache for the terms
    type_:WidgetConfig:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigOutputAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language_selector:
          type: boolean
          default: false
          description: Whether to show the language selector
        supports_text_only:
          type: boolean
          default: true
          description: Whether the widget can switch to text only mode
        custom_avatar_path:
          type: string
          description: The custom avatar path
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePreset'
          description: Language presets for the widget
    type_:SoftTimeoutConfigOverrideConfig:
      type: object
      properties:
        message:
          type: boolean
          default: false
          description: Whether to allow overriding the message field.
    type_:TurnConfigOverrideConfig:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:TtsConversationalConfigOverrideConfig:
      type: object
      properties:
        voice_id:
          type: boolean
          default: false
          description: Whether to allow overriding the voice_id field.
        stability:
          type: boolean
          default: false
          description: Whether to allow overriding the stability field.
        speed:
          type: boolean
          default: false
          description: Whether to allow overriding the speed field.
        similarity_boost:
          type: boolean
          default: false
          description: Whether to allow overriding the similarity_boost field.
    type_:ConversationConfigOverrideConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: Whether to allow overriding the text_only field.
    type_:PromptAgentApiModelOverrideConfig:
      type: object
      properties:
        prompt:
          type: boolean
          default: false
          description: Whether to allow overriding the prompt field.
        llm:
          type: boolean
          default: false
          description: Whether to allow overriding the llm field.
        native_mcp_server_ids:
          type: boolean
          default: false
          description: Whether to allow overriding the native_mcp_server_ids field.
    type_:AgentConfigOverrideConfig:
      type: object
      properties:
        first_message:
          type: boolean
          default: false
          description: Whether to allow overriding the first_message field.
        language:
          type: boolean
          default: false
          description: Whether to allow overriding the language field.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationConfigClientOverrideConfigInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigInput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigInput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:AgentWorkspaceOverridesInput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:AttachedTestModel:
      type: object
      properties:
        test_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - test_id
    type_:AgentTestingSettings:
      type: object
      properties:
        attached_tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AttachedTestModel'
          description: List of test IDs that should be run for this agent
    type_:AuthSettings:
      type: object
      properties:
        enable_auth:
          type: boolean
          default: false
          description: >-
            If set to true, starting a conversation with an agent will require a
            signed token
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            A list of hosts that are allowed to start conversations with the
            agent
        require_origin_header:
          type: boolean
          default: false
          description: >-
            When enabled, connections with no origin header will be rejected. If
            the allowlist is empty, this option has no effect.
        shareable_token:
          type: string
          description: >-
            A shareable token that can be used to start a conversation with the
            agent
    type_:AgentCallLimits:
      type: object
      properties:
        agent_concurrency_limit:
          type: integer
          default: -1
          description: >-
            The maximum number of concurrent conversations. -1 indicates that
            there is no maximum
        daily_limit:
          type: integer
          default: 100000
          description: The maximum number of conversations per day
        bursting_enabled:
          type: boolean
          default: true
          description: >-
            Whether to enable bursting. If true, exceeding workspace concurrency
            limit will be allowed up to 3 times the limit. Calls will be charged
            at double rate when exceeding the limit.
    type_:PrivacyConfig:
      type: object
      properties:
        record_voice:
          type: boolean
          default: true
          description: Whether to record the conversation
        retention_days:
          type: integer
          default: -1
          description: >-
            The number of days to retain the conversation. -1 indicates there is
            no retention limit
        delete_transcript_and_pii:
          type: boolean
          default: false
          description: Whether to delete the transcript and PII
        delete_audio:
          type: boolean
          default: false
          description: Whether to delete the audio
        apply_to_existing_conversations:
          type: boolean
          default: false
          description: Whether to apply the privacy settings to existing conversations
        zero_retention_mode:
          type: boolean
          default: false
          description: Whether to enable zero retention mode - no PII data is stored
    type_:AgentPlatformSettingsRequestModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigInput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesInput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_4
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_1
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_2
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_3
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_4
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:CreateAgentResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: ID of the created agent
      required:
        - agent_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.create({});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.create()

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/create"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/create")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/create', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/create");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/create")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get agent

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}

Retrieve config for an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get agent
  version: endpoint_conversationalAi/agents.get
paths:
  /v1/convai/agents/{agent_id}:
    get:
      operationId: get
      summary: Get agent
      description: Retrieve config for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetAgentResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfig:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfig:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          default: -1
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          default: Hhmmmm...yeah.
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          default: false
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfig:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          default: 7
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          default: -1
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfig'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          default: false
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          default: cjVigY5qzO86Huf0OWal
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          default: 0.5
          description: The stability of generated speech
        speed:
          type: number
          format: double
          default: 1
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          default: 0.8
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          default: 600
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          default: false
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetOutput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfig:
      type: object
      properties: {}
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ConversationalConfig:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfig'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfig'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOutput'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfig'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfig'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfig'
          description: Agent specific configuration
    type_:AgentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
          description: The creation time of the agent in unix seconds
        updated_at_unix_secs:
          type: integer
          description: The last update time of the agent in unix seconds
      required:
        - created_at_unix_secs
        - updated_at_unix_secs
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:EvaluationSettings:
      type: object
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
          description: Individual criteria that the agent should be evaluated against
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigOutputAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetTermsTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:WidgetLanguagePreset:
      type: object
      properties:
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
        terms_translation:
          $ref: '#/components/schemas/type_:WidgetTermsTranslation'
          description: The translation cache for the terms
    type_:WidgetConfig:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigOutputAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language_selector:
          type: boolean
          default: false
          description: Whether to show the language selector
        supports_text_only:
          type: boolean
          default: true
          description: Whether the widget can switch to text only mode
        custom_avatar_path:
          type: string
          description: The custom avatar path
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePreset'
          description: Language presets for the widget
    type_:SoftTimeoutConfigOverrideConfig:
      type: object
      properties:
        message:
          type: boolean
          default: false
          description: Whether to allow overriding the message field.
    type_:TurnConfigOverrideConfig:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:TtsConversationalConfigOverrideConfig:
      type: object
      properties:
        voice_id:
          type: boolean
          default: false
          description: Whether to allow overriding the voice_id field.
        stability:
          type: boolean
          default: false
          description: Whether to allow overriding the stability field.
        speed:
          type: boolean
          default: false
          description: Whether to allow overriding the speed field.
        similarity_boost:
          type: boolean
          default: false
          description: Whether to allow overriding the similarity_boost field.
    type_:ConversationConfigOverrideConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: Whether to allow overriding the text_only field.
    type_:PromptAgentApiModelOverrideConfig:
      type: object
      properties:
        prompt:
          type: boolean
          default: false
          description: Whether to allow overriding the prompt field.
        llm:
          type: boolean
          default: false
          description: Whether to allow overriding the llm field.
        native_mcp_server_ids:
          type: boolean
          default: false
          description: Whether to allow overriding the native_mcp_server_ids field.
    type_:AgentConfigOverrideConfig:
      type: object
      properties:
        first_message:
          type: boolean
          default: false
          description: Whether to allow overriding the first_message field.
        language:
          type: boolean
          default: false
          description: Whether to allow overriding the language field.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationConfigClientOverrideConfigOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigOutput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigOutput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:AgentWorkspaceOverridesOutput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:AttachedTestModel:
      type: object
      properties:
        test_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - test_id
    type_:AgentTestingSettings:
      type: object
      properties:
        attached_tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AttachedTestModel'
          description: List of test IDs that should be run for this agent
    type_:AuthSettings:
      type: object
      properties:
        enable_auth:
          type: boolean
          default: false
          description: >-
            If set to true, starting a conversation with an agent will require a
            signed token
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            A list of hosts that are allowed to start conversations with the
            agent
        require_origin_header:
          type: boolean
          default: false
          description: >-
            When enabled, connections with no origin header will be rejected. If
            the allowlist is empty, this option has no effect.
        shareable_token:
          type: string
          description: >-
            A shareable token that can be used to start a conversation with the
            agent
    type_:AgentCallLimits:
      type: object
      properties:
        agent_concurrency_limit:
          type: integer
          default: -1
          description: >-
            The maximum number of concurrent conversations. -1 indicates that
            there is no maximum
        daily_limit:
          type: integer
          default: 100000
          description: The maximum number of conversations per day
        bursting_enabled:
          type: boolean
          default: true
          description: >-
            Whether to enable bursting. If true, exceeding workspace concurrency
            limit will be allowed up to 3 times the limit. Calls will be charged
            at double rate when exceeding the limit.
    type_:PrivacyConfig:
      type: object
      properties:
        record_voice:
          type: boolean
          default: true
          description: Whether to record the conversation
        retention_days:
          type: integer
          default: -1
          description: >-
            The number of days to retain the conversation. -1 indicates there is
            no retention limit
        delete_transcript_and_pii:
          type: boolean
          default: false
          description: Whether to delete the transcript and PII
        delete_audio:
          type: boolean
          default: false
          description: Whether to delete the audio
        apply_to_existing_conversations:
          type: boolean
          default: false
          description: Whether to apply the privacy settings to existing conversations
        zero_retention_mode:
          type: boolean
          default: false
          description: Whether to enable zero retention mode - no PII data is stored
    type_:SafetyResponseModel:
      type: object
      properties:
        is_blocked_ivc:
          type: boolean
          default: false
        is_blocked_non_ivc:
          type: boolean
          default: false
        ignore_safety_evaluation:
          type: boolean
          default: false
    type_:AgentPlatformSettingsResponseModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigOutput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesOutput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
        safety:
          $ref: '#/components/schemas/type_:SafetyResponseModel'
    type_:PhoneNumberAgentInfo:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        agent_name:
          type: string
          description: The name of the agent
      required:
        - agent_id
        - agent_name
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: SIP headers for INVITE request
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        has_outbound_trunk:
          type: boolean
          default: false
          description: Whether a LiveKit SIP outbound trunk is configured
      required:
        - address
        - transport
        - media_encryption
        - has_auth_credentials
    type_:GetPhoneNumberInboundSipTrunkConfigResponseModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
      required:
        - allowed_addresses
        - media_encryption
        - has_auth_credentials
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_:GetAgentResponseModelPhoneNumbersItem:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
            provider_config:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
            outbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
              description: Configuration of the Outbound SIP trunk - if configured.
            inbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberInboundSipTrunkConfigResponseModel
              description: Configuration of the Inbound SIP trunk - if configured.
            livekit_stack:
              $ref: '#/components/schemas/type_:LivekitStackType'
              description: Type of Livekit stack used for this number.
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
            - livekit_stack
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
      discriminator:
        propertyName: provider
    type_:GetWhatsAppAccountResponse:
      type: object
      properties:
        business_account_id:
          type: string
        phone_number_id:
          type: string
        business_account_name:
          type: string
        phone_number_name:
          type: string
        phone_number:
          type: string
        assigned_agent_id:
          type: string
        assigned_agent_name:
          type: string
      required:
        - business_account_id
        - phone_number_id
        - business_account_name
        - phone_number_name
        - phone_number
    type_:AstOrOperatorNodeOutputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeOutputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelOutputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelOutputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelOutputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelOutputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelOutputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionOutput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
      required:
        - x
        - 'y'
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalConfigWorkflowOverrideOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:BuiltInToolsWorkflowOverrideOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_1
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_2
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_3
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideOutputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:PromptAgentApiModelWorkflowOverrideOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideOutput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideOutput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideOutput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideOutput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelOutputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelOutputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowResponseModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
            - position
            - edge_order
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideOutput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - conversation_config
            - additional_prompt
            - additional_knowledge_base
            - additional_tool_ids
            - position
            - edge_order
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelOutputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelOutputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - custom_sip_headers
            - position
            - edge_order
            - transfer_destination
            - transfer_type
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - position
            - edge_order
            - agent_id
            - delay_ms
            - enable_transferred_agent_first_message
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
            - position
            - edge_order
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
            - position
            - edge_order
            - tools
      discriminator:
        propertyName: type
    type_:AgentWorkflowResponseModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelOutput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowResponseModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
      required:
        - edges
        - nodes
        - prevent_subagent_loops
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:GetAgentResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        name:
          type: string
          description: The name of the agent
        conversation_config:
          $ref: '#/components/schemas/type_:ConversationalConfig'
          description: The conversation configuration of the agent
        metadata:
          $ref: '#/components/schemas/type_:AgentMetadataResponseModel'
          description: The metadata of the agent
        platform_settings:
          $ref: '#/components/schemas/type_:AgentPlatformSettingsResponseModel'
          description: The platform settings of the agent
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/type_:GetAgentResponseModelPhoneNumbersItem'
          description: The phone numbers of the agent
        whatsapp_accounts:
          type: array
          items:
            $ref: '#/components/schemas/type_:GetWhatsAppAccountResponse'
          description: WhatsApp accounts assigned to the agent
        workflow:
          $ref: '#/components/schemas/type_:AgentWorkflowResponseModel'
          description: The workflow of the agent
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the agent for the user
        tags:
          type: array
          items:
            type: string
          description: Agent tags used to categorize the agent
        version_id:
          type: string
          description: The ID of the version the agent is on
        branch_id:
          type: string
          description: The ID of the branch the agent is on
        main_branch_id:
          type: string
          description: The ID of the main branch for this agent
      required:
        - agent_id
        - name
        - conversation_config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List agents

GET https://api.elevenlabs.io/v1/convai/agents

Returns a list of your agents and their metadata.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Agents
  version: endpoint_conversationalAi/agents.list
paths:
  /v1/convai/agents:
    get:
      operationId: list
      summary: List Agents
      description: Returns a list of your agents and their metadata.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: page_size
          in: query
          description: >-
            How many Agents to return at maximum. Can not exceed 100, defaults
            to 30.
          required: false
          schema:
            type: integer
            default: 30
        - name: search
          in: query
          description: Search by agents name.
          required: false
          schema:
            type: string
        - name: archived
          in: query
          description: Filter agents by archived status
          required: false
          schema:
            type: boolean
        - name: show_only_owned_agents
          in: query
          description: >-
            If set to true, the endpoint will omit any agents that were shared
            with you by someone else and include only the ones you own
          required: false
          schema:
            type: boolean
            default: false
        - name: sort_direction
          in: query
          description: The direction to sort the results
          required: false
          schema:
            $ref: '#/components/schemas/type_:SortDirection'
        - name: sort_by
          in: query
          description: The field to sort the results by
          required: false
          schema:
            $ref: '#/components/schemas/type_:AgentSortBy'
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetAgentsPageResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:SortDirection:
      type: string
      enum:
        - value: asc
        - value: desc
    type_:AgentSortBy:
      type: string
      enum:
        - value: name
        - value: created_at
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentSummaryResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        name:
          type: string
          description: The name of the agent
        tags:
          type: array
          items:
            type: string
          description: Agent tags used to categorize the agent
        created_at_unix_secs:
          type: integer
          description: The creation time of the agent in unix seconds
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the agent
        last_call_time_unix_secs:
          type: integer
          description: >-
            The time of the most recent call in unix seconds, null if no calls
            have been made
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
      required:
        - agent_id
        - name
        - tags
        - created_at_unix_secs
        - access_info
    type_:GetAgentsPageResponseModel:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentSummaryResponseModel'
          description: A list of agents and their metadata
        next_cursor:
          type: string
          description: The next cursor to paginate through the agents
        has_more:
          type: boolean
          description: Whether there are more agents to paginate through
      required:
        - agents
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.list({
        pageSize: 1,
        search: "search",
        archived: true,
        showOnlyOwnedAgents: true,
        sortDirection: "asc",
        sortBy: "name",
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.list(
    page_size=1,
    search="search",
    archived=True,
    show_only_owned_agents=True,
    sort_direction="asc",
    sort_by="name",
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents?page_size=1&search=search&archived=true&show_only_owned_agents=true&sort_direction=asc&sort_by=name&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update agent

PATCH https://api.elevenlabs.io/v1/convai/agents/{agent_id}
Content-Type: application/json

Patches an Agent settings

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update agent
  version: endpoint_conversationalAi/agents.update
paths:
  /v1/convai/agents/{agent_id}:
    patch:
      operationId: update
      summary: Update agent
      description: Patches an Agent settings
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetAgentResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_config:
                  $ref: '#/components/schemas/type_:ConversationalConfig'
                  description: Conversation configuration for an agent
                platform_settings:
                  $ref: '#/components/schemas/type_:AgentPlatformSettingsRequestModel'
                  description: >-
                    Platform settings for the agent are all settings that aren't
                    related to the conversation orchestration and content.
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: >-
                    Workflow for the agent. This is used to define the flow of
                    the conversation and how the agent interacts with tools.
                name:
                  type: string
                  description: A name to make the agent easier to find
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags to help classify and filter the agent
                version_description:
                  type: string
                  description: >-
                    Description for this version when publishing changes (only
                    applicable for versioned agents)
                procedure_refs:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/agents:BodyPatchesAnAgentSettingsV1ConvaiAgentsAgentIdPatchProcedureRefsItem
                  description: List of procedure refs used for this agent version.
components:
  schemas:
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfig:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfig:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          default: -1
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          default: Hhmmmm...yeah.
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          default: false
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfig:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          default: 7
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          default: -1
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfig'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          default: false
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          default: cjVigY5qzO86Huf0OWal
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          default: 0.5
          description: The stability of generated speech
        speed:
          type: number
          format: double
          default: 1
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          default: 0.8
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          default: 600
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          default: false
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetOutput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfig:
      type: object
      properties: {}
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ConversationalConfig:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfig'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfig'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOutput'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfig'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfig'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfig'
          description: Agent specific configuration
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:EvaluationSettings:
      type: object
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
          description: Individual criteria that the agent should be evaluated against
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigOutputAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetTermsTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:WidgetLanguagePreset:
      type: object
      properties:
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
        terms_translation:
          $ref: '#/components/schemas/type_:WidgetTermsTranslation'
          description: The translation cache for the terms
    type_:WidgetConfig:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigOutputAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language_selector:
          type: boolean
          default: false
          description: Whether to show the language selector
        supports_text_only:
          type: boolean
          default: true
          description: Whether the widget can switch to text only mode
        custom_avatar_path:
          type: string
          description: The custom avatar path
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePreset'
          description: Language presets for the widget
    type_:SoftTimeoutConfigOverrideConfig:
      type: object
      properties:
        message:
          type: boolean
          default: false
          description: Whether to allow overriding the message field.
    type_:TurnConfigOverrideConfig:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:TtsConversationalConfigOverrideConfig:
      type: object
      properties:
        voice_id:
          type: boolean
          default: false
          description: Whether to allow overriding the voice_id field.
        stability:
          type: boolean
          default: false
          description: Whether to allow overriding the stability field.
        speed:
          type: boolean
          default: false
          description: Whether to allow overriding the speed field.
        similarity_boost:
          type: boolean
          default: false
          description: Whether to allow overriding the similarity_boost field.
    type_:ConversationConfigOverrideConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: Whether to allow overriding the text_only field.
    type_:PromptAgentApiModelOverrideConfig:
      type: object
      properties:
        prompt:
          type: boolean
          default: false
          description: Whether to allow overriding the prompt field.
        llm:
          type: boolean
          default: false
          description: Whether to allow overriding the llm field.
        native_mcp_server_ids:
          type: boolean
          default: false
          description: Whether to allow overriding the native_mcp_server_ids field.
    type_:AgentConfigOverrideConfig:
      type: object
      properties:
        first_message:
          type: boolean
          default: false
          description: Whether to allow overriding the first_message field.
        language:
          type: boolean
          default: false
          description: Whether to allow overriding the language field.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationConfigClientOverrideConfigInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigInput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigInput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:AgentWorkspaceOverridesInput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:AttachedTestModel:
      type: object
      properties:
        test_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - test_id
    type_:AgentTestingSettings:
      type: object
      properties:
        attached_tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AttachedTestModel'
          description: List of test IDs that should be run for this agent
    type_:AuthSettings:
      type: object
      properties:
        enable_auth:
          type: boolean
          default: false
          description: >-
            If set to true, starting a conversation with an agent will require a
            signed token
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            A list of hosts that are allowed to start conversations with the
            agent
        require_origin_header:
          type: boolean
          default: false
          description: >-
            When enabled, connections with no origin header will be rejected. If
            the allowlist is empty, this option has no effect.
        shareable_token:
          type: string
          description: >-
            A shareable token that can be used to start a conversation with the
            agent
    type_:AgentCallLimits:
      type: object
      properties:
        agent_concurrency_limit:
          type: integer
          default: -1
          description: >-
            The maximum number of concurrent conversations. -1 indicates that
            there is no maximum
        daily_limit:
          type: integer
          default: 100000
          description: The maximum number of conversations per day
        bursting_enabled:
          type: boolean
          default: true
          description: >-
            Whether to enable bursting. If true, exceeding workspace concurrency
            limit will be allowed up to 3 times the limit. Calls will be charged
            at double rate when exceeding the limit.
    type_:PrivacyConfig:
      type: object
      properties:
        record_voice:
          type: boolean
          default: true
          description: Whether to record the conversation
        retention_days:
          type: integer
          default: -1
          description: >-
            The number of days to retain the conversation. -1 indicates there is
            no retention limit
        delete_transcript_and_pii:
          type: boolean
          default: false
          description: Whether to delete the transcript and PII
        delete_audio:
          type: boolean
          default: false
          description: Whether to delete the audio
        apply_to_existing_conversations:
          type: boolean
          default: false
          description: Whether to apply the privacy settings to existing conversations
        zero_retention_mode:
          type: boolean
          default: false
          description: Whether to enable zero retention mode - no PII data is stored
    type_:AgentPlatformSettingsRequestModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigInput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesInput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_4
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_1
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_2
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_3
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_4
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:ProcedureVersionRef:
      type: object
      properties:
        procedure_id:
          type: string
          description: Procedure ID
        version_id:
          type: string
          description: Version ID of the procedure version.
      required:
        - procedure_id
        - version_id
    type_:ProcedureDraftRef:
      type: object
      properties:
        procedure_id:
          type: string
          description: Procedure ID
      required:
        - procedure_id
    type_conversationalAi/agents:BodyPatchesAnAgentSettingsV1ConvaiAgentsAgentIdPatchProcedureRefsItem:
      oneOf:
        - $ref: '#/components/schemas/type_:ProcedureVersionRef'
        - $ref: '#/components/schemas/type_:ProcedureDraftRef'
    type_:AgentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
          description: The creation time of the agent in unix seconds
        updated_at_unix_secs:
          type: integer
          description: The last update time of the agent in unix seconds
      required:
        - created_at_unix_secs
        - updated_at_unix_secs
    type_:ConversationConfigClientOverrideConfigOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigOutput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigOutput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:AgentWorkspaceOverridesOutput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:SafetyResponseModel:
      type: object
      properties:
        is_blocked_ivc:
          type: boolean
          default: false
        is_blocked_non_ivc:
          type: boolean
          default: false
        ignore_safety_evaluation:
          type: boolean
          default: false
    type_:AgentPlatformSettingsResponseModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigOutput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesOutput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
        safety:
          $ref: '#/components/schemas/type_:SafetyResponseModel'
    type_:PhoneNumberAgentInfo:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        agent_name:
          type: string
          description: The name of the agent
      required:
        - agent_id
        - agent_name
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: SIP headers for INVITE request
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        has_outbound_trunk:
          type: boolean
          default: false
          description: Whether a LiveKit SIP outbound trunk is configured
      required:
        - address
        - transport
        - media_encryption
        - has_auth_credentials
    type_:GetPhoneNumberInboundSipTrunkConfigResponseModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
      required:
        - allowed_addresses
        - media_encryption
        - has_auth_credentials
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_:GetAgentResponseModelPhoneNumbersItem:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
            provider_config:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
            outbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
              description: Configuration of the Outbound SIP trunk - if configured.
            inbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberInboundSipTrunkConfigResponseModel
              description: Configuration of the Inbound SIP trunk - if configured.
            livekit_stack:
              $ref: '#/components/schemas/type_:LivekitStackType'
              description: Type of Livekit stack used for this number.
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
            - livekit_stack
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
      discriminator:
        propertyName: provider
    type_:GetWhatsAppAccountResponse:
      type: object
      properties:
        business_account_id:
          type: string
        phone_number_id:
          type: string
        business_account_name:
          type: string
        phone_number_name:
          type: string
        phone_number:
          type: string
        assigned_agent_id:
          type: string
        assigned_agent_name:
          type: string
      required:
        - business_account_id
        - phone_number_id
        - business_account_name
        - phone_number_name
        - phone_number
    type_:AstOrOperatorNodeOutputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeOutputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeOutputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeOutputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelOutputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:AstAndOperatorNodeOutputChildrenItem
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeOutputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeOutputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeOutputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelOutputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelOutputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelOutput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelOutputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelOutputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionOutput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
      required:
        - x
        - 'y'
    type_:TtsConversationalConfigWorkflowOverrideOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:BuiltInToolsWorkflowOverrideOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:PromptAgentApiModelWorkflowOverrideOutputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:PromptAgentApiModelWorkflowOverrideOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideOutput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideOutput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideOutput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideOutput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideOutput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelOutputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelOutputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:AgentWorkflowResponseModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
            - position
            - edge_order
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideOutput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - conversation_config
            - additional_prompt
            - additional_knowledge_base
            - additional_tool_ids
            - position
            - edge_order
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelOutputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelOutputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - custom_sip_headers
            - position
            - edge_order
            - transfer_destination
            - transfer_type
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - position
            - edge_order
            - agent_id
            - delay_ms
            - enable_transferred_agent_first_message
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
            - position
            - edge_order
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionOutput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
            - position
            - edge_order
            - tools
      discriminator:
        propertyName: type
    type_:AgentWorkflowResponseModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelOutput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowResponseModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
      required:
        - edges
        - nodes
        - prevent_subagent_loops
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:GetAgentResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        name:
          type: string
          description: The name of the agent
        conversation_config:
          $ref: '#/components/schemas/type_:ConversationalConfig'
          description: The conversation configuration of the agent
        metadata:
          $ref: '#/components/schemas/type_:AgentMetadataResponseModel'
          description: The metadata of the agent
        platform_settings:
          $ref: '#/components/schemas/type_:AgentPlatformSettingsResponseModel'
          description: The platform settings of the agent
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/type_:GetAgentResponseModelPhoneNumbersItem'
          description: The phone numbers of the agent
        whatsapp_accounts:
          type: array
          items:
            $ref: '#/components/schemas/type_:GetWhatsAppAccountResponse'
          description: WhatsApp accounts assigned to the agent
        workflow:
          $ref: '#/components/schemas/type_:AgentWorkflowResponseModel'
          description: The workflow of the agent
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the agent for the user
        tags:
          type: array
          items:
            type: string
          description: Agent tags used to categorize the agent
        version_id:
          type: string
          description: The ID of the version the agent is on
        branch_id:
          type: string
          description: The ID of the branch the agent is on
        main_branch_id:
          type: string
          description: The ID of the main branch for this agent
      required:
        - agent_id
        - name
        - conversation_config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.update("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.update(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete agent

DELETE https://api.elevenlabs.io/v1/convai/agents/{agent_id}

Delete an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete agent
  version: endpoint_conversationalAi/agents.delete
paths:
  /v1/convai/agents/{agent_id}:
    delete:
      operationId: delete
      summary: Delete agent
      description: Delete an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.delete("agent_3701k3ttaq12ewp8b7qv5rfyszkz");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.delete(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Duplicate agent

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/duplicate
Content-Type: application/json

Create a new agent by duplicating an existing one

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/duplicate

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Duplicate Agent
  version: endpoint_conversationalAi/agents.duplicate
paths:
  /v1/convai/agents/{agent_id}/duplicate:
    post:
      operationId: duplicate
      summary: Duplicate Agent
      description: Create a new agent by duplicating an existing one
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreateAgentResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A name to make the agent easier to find
components:
  schemas:
    type_:CreateAgentResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: ID of the created agent
      required:
        - agent_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.duplicate("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.duplicate(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/duplicate")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get link

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/link

Get the current link used to share the agent with others

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/get-link

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Shareable Agent Link
  version: endpoint_conversationalAi/agents/link.get
paths:
  /v1/convai/agents/{agent_id}/link:
    get:
      operationId: get
      summary: Get Shareable Agent Link
      description: Get the current link used to share the agent with others
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/link
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetAgentLinkResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ConversationTokenPurpose:
      type: string
      enum:
        - value: signed_url
        - value: shareable_link
    type_:ConversationTokenDbModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        conversation_token:
          type: string
          description: The token for the agent
        expiration_time_unix_secs:
          type: integer
          description: The expiration time of the token in unix seconds
        conversation_id:
          type: string
          description: The ID of the conversation
        purpose:
          $ref: '#/components/schemas/type_:ConversationTokenPurpose'
          description: The purpose of the token
        token_requester_user_id:
          type: string
          description: The user ID of the entity who requested the token
      required:
        - agent_id
        - conversation_token
    type_:GetAgentLinkResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        token:
          $ref: '#/components/schemas/type_:ConversationTokenDbModel'
          description: The token data for the agent
      required:
        - agent_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.link.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.link.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/link")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Simulate conversation

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/simulate-conversation
Content-Type: application/json

Run a conversation between the agent and a simulated user.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/simulate-conversation

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Simulates A Conversation
  version: endpoint_conversationalAi/agents.simulate_conversation
paths:
  /v1/convai/agents/{agent_id}/simulate-conversation:
    post:
      operationId: simulate-conversation
      summary: Simulates A Conversation
      description: Run a conversation between the agent and a simulated user.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentSimulatedChatTestResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                simulation_specification:
                  $ref: >-
                    #/components/schemas/type_:ConversationSimulationSpecification
                  description: >-
                    A specification detailing how the conversation should be
                    simulated
                extra_evaluation_criteria:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
                  description: A list of evaluation criteria to test
                new_turns_limit:
                  type: integer
                  default: 10000
                  description: >-
                    Maximum number of new turns to generate in the conversation
                    simulation
              required:
                - simulation_specification
components:
  schemas:
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ToolMockConfig:
      type: object
      properties:
        default_return_value:
          type: string
          default: Tool Called.
        default_is_error:
          type: boolean
          default: false
    type_:ConversationHistoryTranscriptCommonModelInputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_1
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_1
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - &ref_4
                  type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - &ref_5
                  type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - &ref_6
                  type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - &ref_7
                  type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - &ref_8
                  type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - &ref_9
                  type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - &ref_10
                  type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - &ref_11
                  type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - &ref_12
                  type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - &ref_13
                  type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelInputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:WorkflowToolResponseModelInputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelInputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelInput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/type_:WorkflowToolResponseModelInputStepsItem'
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelInput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageInput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelInputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelInput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageInput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:ConversationSimulationSpecificationDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationSimulationSpecification:
      type: object
      properties:
        simulated_user_config:
          $ref: '#/components/schemas/type_:AgentConfig'
        tool_mock_config:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ToolMockConfig'
        partial_conversation_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
          description: >-
            A partial conversation history to start the simulation from. If
            empty, simulation starts fresh.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationSimulationSpecificationDynamicVariablesValue
      required:
        - simulated_user_config
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_1
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - *ref_2
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - *ref_3
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - *ref_4
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - *ref_5
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - *ref_6
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - *ref_7
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - *ref_8
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - *ref_9
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - *ref_10
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - *ref_11
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - *ref_12
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - *ref_13
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:EvaluationSuccessResult:
      type: string
      enum:
        - value: success
        - value: failure
        - value: unknown
    type_:ConversationHistoryEvaluationCriteriaResultCommonModel:
      type: object
      properties:
        criteria_id:
          type: string
        result:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        rationale:
          type: string
      required:
        - criteria_id
        - result
        - rationale
    type_:DataCollectionResultCommonModel:
      type: object
      properties:
        data_collection_id:
          type: string
        value:
          description: Any type
        json_schema:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        rationale:
          type: string
      required:
        - data_collection_id
        - rationale
    type_:ConversationHistoryAnalysisCommonModel:
      type: object
      properties:
        evaluation_criteria_results:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryEvaluationCriteriaResultCommonModel
        data_collection_results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:DataCollectionResultCommonModel'
        evaluation_criteria_results_list:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryEvaluationCriteriaResultCommonModel
        data_collection_results_list:
          type: array
          items:
            $ref: '#/components/schemas/type_:DataCollectionResultCommonModel'
        call_successful:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        transcript_summary:
          type: string
        call_summary_title:
          type: string
      required:
        - call_successful
        - transcript_summary
    type_:AgentSimulatedChatTestResponseModel:
      type: object
      properties:
        simulated_conversation:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        analysis:
          $ref: '#/components/schemas/type_:ConversationHistoryAnalysisCommonModel'
      required:
        - simulated_conversation
        - analysis

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.simulateConversation("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        simulationSpecification: {
            simulatedUserConfig: {
                firstMessage: "Hello, how can I help you today?",
                language: "en",
                disableFirstMessageInterruptions: false,
            },
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.simulate_conversation(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    simulation_specification={
        "simulated_user_config": {
            "first_message": "Hello, how can I help you today?",
            "language": "en",
            "disable_first_message_interruptions": False
        }
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation"

	payload := strings.NewReader("{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation")
  .header("Content-Type", "application/json")
  .body("{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation', [
  'body' => '{
  "simulation_specification": {
    "simulated_user_config": {
      "first_message": "Hello, how can I help you today?",
      "language": "en",
      "disable_first_message_interruptions": false
    }
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["simulation_specification": ["simulated_user_config": [
      "first_message": "Hello, how can I help you today?",
      "language": "en",
      "disable_first_message_interruptions": false
    ]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Stream simulate conversation

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/simulate-conversation/stream
Content-Type: application/json

Run a conversation between the agent and a simulated user and stream back the response. Response is streamed back as partial lists of messages that should be concatenated and once the conversation has complete a single final message with the conversation analysis will be sent.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/simulate-conversation-stream

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Simulates A Conversation (Stream)
  version: endpoint_conversationalAi/agents.simulate_conversation_stream
paths:
  /v1/convai/agents/{agent_id}/simulate-conversation/stream:
    post:
      operationId: simulate-conversation-stream
      summary: Simulates A Conversation (Stream)
      description: >-
        Run a conversation between the agent and a simulated user and stream
        back the response. Response is streamed back as partial lists of
        messages that should be concatenated and once the conversation has
        complete a single final message with the conversation analysis will be
        sent.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                simulation_specification:
                  $ref: >-
                    #/components/schemas/type_:ConversationSimulationSpecification
                  description: >-
                    A specification detailing how the conversation should be
                    simulated
                extra_evaluation_criteria:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
                  description: A list of evaluation criteria to test
                new_turns_limit:
                  type: integer
                  default: 10000
                  description: >-
                    Maximum number of new turns to generate in the conversation
                    simulation
              required:
                - simulation_specification
components:
  schemas:
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ToolMockConfig:
      type: object
      properties:
        default_return_value:
          type: string
          default: Tool Called.
        default_is_error:
          type: boolean
          default: false
    type_:ConversationHistoryTranscriptCommonModelInputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_1
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_1
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelInputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:WorkflowToolResponseModelInputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelInputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelInput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/type_:WorkflowToolResponseModelInputStepsItem'
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelInput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageInput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelInputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelInput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageInput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:ConversationSimulationSpecificationDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationSimulationSpecification:
      type: object
      properties:
        simulated_user_config:
          $ref: '#/components/schemas/type_:AgentConfig'
        tool_mock_config:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ToolMockConfig'
        partial_conversation_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
          description: >-
            A partial conversation history to start the simulation from. If
            empty, simulation starts fresh.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationSimulationSpecificationDynamicVariablesValue
      required:
        - simulated_user_config
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.simulateConversationStream("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        simulationSpecification: {
            simulatedUserConfig: {
                firstMessage: "Hello, how can I help you today?",
                language: "en",
                disableFirstMessageInterruptions: false,
            },
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.simulate_conversation_stream(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    simulation_specification={
        "simulated_user_config": {
            "first_message": "Hello, how can I help you today?",
            "language": "en",
            "disable_first_message_interruptions": False
        }
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream"

	payload := strings.NewReader("{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream")
  .header("Content-Type", "application/json")
  .body("{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream', [
  'body' => '{
  "simulation_specification": {
    "simulated_user_config": {
      "first_message": "Hello, how can I help you today?",
      "language": "en",
      "disable_first_message_interruptions": false
    }
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"simulation_specification\": {\n    \"simulated_user_config\": {\n      \"first_message\": \"Hello, how can I help you today?\",\n      \"language\": \"en\",\n      \"disable_first_message_interruptions\": false\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["simulation_specification": ["simulated_user_config": [
      "first_message": "Hello, how can I help you today?",
      "language": "en",
      "disable_first_message_interruptions": false
    ]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/simulate-conversation/stream")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Calculate expected LLM usage

POST https://api.elevenlabs.io/v1/convai/agent/{agent_id}/llm-usage/calculate
Content-Type: application/json

Calculates expected number of LLM tokens needed for the specified agent.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/calculate

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Calculate Expected Llm Usage For An Agent
  version: endpoint_conversationalAi/agents/llmUsage.calculate
paths:
  /v1/convai/agent/{agent_id}/llm-usage/calculate:
    post:
      operationId: calculate
      summary: Calculate Expected Llm Usage For An Agent
      description: Calculates expected number of LLM tokens needed for the specified agent.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/llmUsage
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:LlmUsageCalculatorResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt_length:
                  type: integer
                  description: Length of the prompt in characters.
                number_of_pages:
                  type: integer
                  description: >-
                    Pages of content in pdf documents OR urls in agent's
                    Knowledge Base.
                rag_enabled:
                  type: boolean
                  description: Whether RAG is enabled.
components:
  schemas:
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:LlmUsageCalculatorLlmResponseModel:
      type: object
      properties:
        llm:
          $ref: '#/components/schemas/type_:Llm'
        price_per_minute:
          type: number
          format: double
      required:
        - llm
        - price_per_minute
    type_:LlmUsageCalculatorResponseModel:
      type: object
      properties:
        llm_prices:
          type: array
          items:
            $ref: '#/components/schemas/type_:LlmUsageCalculatorLlmResponseModel'
      required:
        - llm_prices

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.llmUsage.calculate("agent_id", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.llm_usage.calculate(
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent/agent_id/llm-usage/calculate")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get agent summaries

GET https://api.elevenlabs.io/v1/convai/agents/summaries

Returns summaries for the specified agents.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/get-summaries

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Summaries
  version: endpoint_conversationalAi/agents/summaries.get
paths:
  /v1/convai/agents/summaries:
    get:
      operationId: get
      summary: Get Agent Summaries
      description: Returns summaries for the specified agents.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/summaries
      parameters:
        - name: agent_ids
          in: query
          description: List of agent IDs to fetch summaries for
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: >-
                    #/components/schemas/type_conversationalAi/agents/summaries:SummariesGetResponseValue
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentSummaryResponseModel:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        name:
          type: string
          description: The name of the agent
        tags:
          type: array
          items:
            type: string
          description: Agent tags used to categorize the agent
        created_at_unix_secs:
          type: integer
          description: The creation time of the agent in unix seconds
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the agent
        last_call_time_unix_secs:
          type: integer
          description: >-
            The time of the most recent call in unix seconds, null if no calls
            have been made
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
      required:
        - agent_id
        - name
        - tags
        - created_at_unix_secs
        - access_info
    type_conversationalAi/agents/summaries:SummariesGetResponseValue:
      oneOf:
        - type: object
          properties:
            status:
              type: string
              enum:
                - success
              description: 'Discriminator value: success'
            data:
              $ref: '#/components/schemas/type_:AgentSummaryResponseModel'
          required:
            - status
            - data
        - type: object
          properties:
            status:
              type: string
              enum:
                - failure
              description: 'Discriminator value: failure'
            error_code:
              type: integer
            error_status:
              type: string
            error_message:
              type: string
          required:
            - status
            - error_code
            - error_status
            - error_message
      discriminator:
        propertyName: status

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.summaries.get({
        agentIds: [
            "J3Pbu5gP6NNKBscdCdwB",
            "K4Qcu6hQ7OOLCtdeDeXC",
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.summaries.get(
    agent_ids=[
        "J3Pbu5gP6NNKBscdCdwB",
        "K4Qcu6hQ7OOLCtdeDeXC"
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/summaries?agent_ids=%5B%22J3Pbu5gP6NNKBscdCdwB%22%2C%22K4Qcu6hQ7OOLCtdeDeXC%22%5D")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List conversations

GET https://api.elevenlabs.io/v1/convai/conversations

Get all conversations of agents that user owns. With option to restrict to a specific agent.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List conversations
  version: endpoint_conversationalAi/conversations.list
paths:
  /v1/convai/conversations:
    get:
      operationId: list
      summary: List conversations
      description: >-
        Get all conversations of agents that user owns. With option to restrict
        to a specific agent.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
      parameters:
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: agent_id
          in: query
          description: The id of the agent you're taking the action on.
          required: false
          schema:
            type: string
        - name: call_successful
          in: query
          description: The result of the success evaluation
          required: false
          schema:
            $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        - name: call_start_before_unix
          in: query
          description: >-
            Unix timestamp (in seconds) to filter conversations up to this start
            date.
          required: false
          schema:
            type: integer
        - name: call_start_after_unix
          in: query
          description: >-
            Unix timestamp (in seconds) to filter conversations after to this
            start date.
          required: false
          schema:
            type: integer
        - name: call_duration_min_secs
          in: query
          description: Minimum call duration in seconds.
          required: false
          schema:
            type: integer
        - name: call_duration_max_secs
          in: query
          description: Maximum call duration in seconds.
          required: false
          schema:
            type: integer
        - name: rating_max
          in: query
          description: Maximum overall rating (1-5).
          required: false
          schema:
            type: integer
        - name: rating_min
          in: query
          description: Minimum overall rating (1-5).
          required: false
          schema:
            type: integer
        - name: has_feedback_comment
          in: query
          description: Filter conversations with user feedback comments.
          required: false
          schema:
            type: boolean
        - name: user_id
          in: query
          description: Filter conversations by the user ID who initiated them.
          required: false
          schema:
            type: string
        - name: evaluation_params
          in: query
          description: >-
            Evaluation filters. Repeat param. Format: criteria_id:result.
            Example: eval=value_framing:success
          required: false
          schema:
            type: string
        - name: data_collection_params
          in: query
          description: >-
            Data collection filters. Repeat param. Format: id:op:value where op
            is one of eq|neq|gt|gte|lt|lte|in|exists|missing. For in,
            pipe-delimit values.
          required: false
          schema:
            type: string
        - name: tool_names
          in: query
          description: Filter conversations by tool names used during the call.
          required: false
          schema:
            type: string
        - name: main_languages
          in: query
          description: Filter conversations by detected main language (language code).
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: >-
            How many conversations to return at maximum. Can not exceed 100,
            defaults to 30.
          required: false
          schema:
            type: integer
            default: 30
        - name: summary_mode
          in: query
          description: Whether to include transcript summaries in the response.
          required: false
          schema:
            $ref: >-
              #/components/schemas/type_conversationalAi/conversations:ConversationsListRequestSummaryMode
        - name: search
          in: query
          description: Full-text or fuzzy search over transcript messages
          required: false
          schema:
            type: string
        - name: conversation_initiation_source
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:ConversationInitiationSource'
        - name: branch_id
          in: query
          description: Filter conversations by branch ID.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetConversationsPageResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:EvaluationSuccessResult:
      type: string
      enum:
        - value: success
        - value: failure
        - value: unknown
    type_conversationalAi/conversations:ConversationsListRequestSummaryMode:
      type: string
      enum:
        - value: exclude
        - value: include
      default: exclude
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationSummaryResponseModelStatus:
      type: string
      enum:
        - value: initiated
        - value: in-progress
        - value: processing
        - value: done
        - value: failed
    type_:ConversationSummaryResponseModelDirection:
      type: string
      enum:
        - value: inbound
        - value: outbound
    type_:ConversationSummaryResponseModel:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        version_id:
          type: string
        agent_name:
          type: string
        conversation_id:
          type: string
        start_time_unix_secs:
          type: integer
        call_duration_secs:
          type: integer
        message_count:
          type: integer
        status:
          $ref: '#/components/schemas/type_:ConversationSummaryResponseModelStatus'
        call_successful:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        transcript_summary:
          type: string
        call_summary_title:
          type: string
        direction:
          $ref: '#/components/schemas/type_:ConversationSummaryResponseModelDirection'
        rating:
          type: number
          format: double
      required:
        - agent_id
        - conversation_id
        - start_time_unix_secs
        - call_duration_secs
        - message_count
        - status
        - call_successful
    type_:GetConversationsPageResponseModel:
      type: object
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/type_:ConversationSummaryResponseModel'
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - conversations
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.list({
        cursor: "cursor",
        agentId: "agent_id",
        callSuccessful: "success",
        callStartBeforeUnix: 1,
        callStartAfterUnix: 1,
        callDurationMinSecs: 1,
        callDurationMaxSecs: 1,
        ratingMax: 1,
        ratingMin: 1,
        hasFeedbackComment: true,
        userId: "user_id",
        pageSize: 1,
        summaryMode: "exclude",
        search: "search",
        conversationInitiationSource: "unknown",
        branchId: "branch_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.list(
    cursor="cursor",
    agent_id="agent_id",
    call_successful="success",
    call_start_before_unix=1,
    call_start_after_unix=1,
    call_duration_min_secs=1,
    call_duration_max_secs=1,
    rating_max=1,
    rating_min=1,
    has_feedback_comment=True,
    user_id="user_id",
    page_size=1,
    summary_mode="exclude",
    search="search",
    conversation_initiation_source="unknown",
    branch_id="branch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversations?cursor=cursor&agent_id=agent_id&call_successful=success&call_start_before_unix=1&call_start_after_unix=1&call_duration_min_secs=1&call_duration_max_secs=1&rating_max=1&rating_min=1&has_feedback_comment=true&user_id=user_id&page_size=1&summary_mode=exclude&search=search&conversation_initiation_source=unknown&branch_id=branch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get conversation details

GET https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}

Get the details of a particular conversation

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Conversation Details
  version: endpoint_conversationalAi/conversations.get
paths:
  /v1/convai/conversations/{conversation_id}:
    get:
      operationId: get
      summary: Get Conversation Details
      description: Get the details of a particular conversation
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
      parameters:
        - name: conversation_id
          in: path
          description: The id of the conversation you're taking the action on.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetConversationResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetConversationResponseModelStatus:
      type: string
      enum:
        - value: initiated
        - value: in-progress
        - value: processing
        - value: done
        - value: failed
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:ConversationDeletionSettings:
      type: object
      properties:
        deletion_time_unix_secs:
          type: integer
        deleted_logs_at_time_unix_secs:
          type: integer
        deleted_audio_at_time_unix_secs:
          type: integer
        deleted_transcript_at_time_unix_secs:
          type: integer
        delete_transcript_and_pii:
          type: boolean
          default: false
        delete_audio:
          type: boolean
          default: false
    type_:ConversationFeedbackType:
      type: string
      enum:
        - value: thumbs
        - value: rating
    type_:ConversationHistoryFeedbackCommonModel:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ConversationFeedbackType'
        overall_score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        likes:
          type: integer
          default: 0
        dislikes:
          type: integer
          default: 0
        rating:
          type: integer
        comment:
          type: string
    type_:AuthorizationMethod:
      type: string
      enum:
        - value: invalid
        - value: public
        - value: authorization_header
        - value: signed_url
        - value: shareable_link
        - value: livekit_token
        - value: livekit_token_website
        - value: genesys_api_key
        - value: whatsapp
    type_:LlmCategoryUsage:
      type: object
      properties:
        irreversible_generation:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        initiated_generation:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
    type_:ConversationChargingCommonModel:
      type: object
      properties:
        dev_discount:
          type: boolean
          default: false
        is_burst:
          type: boolean
          default: false
        tier:
          type: string
        llm_usage:
          $ref: '#/components/schemas/type_:LlmCategoryUsage'
        llm_price:
          type: number
          format: double
        llm_charge:
          type: integer
        call_charge:
          type: integer
        free_minutes_consumed:
          type: number
          format: double
          default: 0
        free_llm_dollars_consumed:
          type: number
          format: double
          default: 0
    type_:ConversationHistorySipTrunkingPhoneCallModelDirection:
      type: string
      enum:
        - value: inbound
        - value: outbound
    type_:ConversationHistoryTwilioPhoneCallModelDirection:
      type: string
      enum:
        - value: inbound
        - value: outbound
    type_:ConversationHistoryMetadataCommonModelPhoneCall:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_trunking
              description: 'Discriminator value: sip_trunking'
            direction:
              $ref: >-
                #/components/schemas/type_:ConversationHistorySipTrunkingPhoneCallModelDirection
            phone_number_id:
              type: string
            agent_number:
              type: string
            external_number:
              type: string
            call_sid:
              type: string
          required:
            - type
            - direction
            - phone_number_id
            - agent_number
            - external_number
            - call_sid
        - type: object
          properties:
            type:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            direction:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTwilioPhoneCallModelDirection
            phone_number_id:
              type: string
            agent_number:
              type: string
            external_number:
              type: string
            stream_sid:
              type: string
            call_sid:
              type: string
          required:
            - type
            - direction
            - phone_number_id
            - agent_number
            - external_number
            - stream_sid
            - call_sid
      discriminator:
        propertyName: type
    type_:ConversationHistoryBatchCallModel:
      type: object
      properties:
        batch_call_id:
          type: string
        batch_call_recipient_id:
          type: string
      required:
        - batch_call_id
        - batch_call_recipient_id
    type_:ConversationHistoryErrorCommonModel:
      type: object
      properties:
        code:
          type: integer
        reason:
          type: string
      required:
        - code
    type_:ConversationHistoryRagUsageCommonModel:
      type: object
      properties:
        usage_count:
          type: integer
        embedding_model:
          type: string
      required:
        - usage_count
        - embedding_model
    type_:FeatureStatusCommonModel:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        used:
          type: boolean
          default: false
    type_:WorkflowFeaturesUsageCommonModel:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        tool_node:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        standalone_agent_node:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        phone_number_node:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        end_node:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
    type_:TestsFeatureUsageCommonModel:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        tests_ran_after_last_modification:
          type: boolean
          default: false
        tests_ran_in_last_7_days:
          type: boolean
          default: false
    type_:FeaturesUsageCommonModel:
      type: object
      properties:
        language_detection:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        transfer_to_agent:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        transfer_to_number:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        multivoice:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        dtmf_tones:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        external_mcp_servers:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        pii_zrm_workspace:
          type: boolean
          default: false
        pii_zrm_agent:
          type: boolean
          default: false
        tool_dynamic_variable_updates:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        is_livekit:
          type: boolean
          default: false
        voicemail_detection:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
        workflow:
          $ref: '#/components/schemas/type_:WorkflowFeaturesUsageCommonModel'
        agent_testing:
          $ref: '#/components/schemas/type_:TestsFeatureUsageCommonModel'
        versioning:
          $ref: '#/components/schemas/type_:FeatureStatusCommonModel'
    type_:ConversationHistoryElevenAssistantCommonModel:
      type: object
      properties:
        is_eleven_assistant:
          type: boolean
          default: false
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:AsyncConversationMetadataDeliveryStatus:
      type: string
      enum:
        - value: pending
        - value: success
        - value: failed
    type_:AsyncConversationMetadata:
      type: object
      properties:
        delivery_status:
          $ref: '#/components/schemas/type_:AsyncConversationMetadataDeliveryStatus'
        delivery_timestamp:
          type: integer
        delivery_error:
          type: string
        external_system:
          type: string
        external_id:
          type: string
        retry_count:
          type: integer
          default: 0
        last_retry_timestamp:
          type: integer
      required:
        - delivery_status
        - delivery_timestamp
        - external_system
        - external_id
    type_:WhatsAppConversationInfoDirection:
      type: string
      enum:
        - value: inbound
        - value: outbound
        - value: unknown
      default: unknown
    type_:WhatsAppConversationInfo:
      type: object
      properties:
        direction:
          $ref: '#/components/schemas/type_:WhatsAppConversationInfoDirection'
        whatsapp_phone_number_id:
          type: string
        whatsapp_user_id:
          type: string
        awaiting_first_user_message:
          type: boolean
      required:
        - whatsapp_user_id
    type_:AgentDefinitionSource:
      type: string
      enum:
        - value: cli
        - value: ui
        - value: api
        - value: template
        - value: unknown
    type_:ConversationHistoryMetadataCommonModel:
      type: object
      properties:
        start_time_unix_secs:
          type: integer
        accepted_time_unix_secs:
          type: integer
        call_duration_secs:
          type: integer
        cost:
          type: integer
        deletion_settings:
          $ref: '#/components/schemas/type_:ConversationDeletionSettings'
        feedback:
          $ref: '#/components/schemas/type_:ConversationHistoryFeedbackCommonModel'
        authorization_method:
          $ref: '#/components/schemas/type_:AuthorizationMethod'
        charging:
          $ref: '#/components/schemas/type_:ConversationChargingCommonModel'
        phone_call:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryMetadataCommonModelPhoneCall
        batch_call:
          $ref: '#/components/schemas/type_:ConversationHistoryBatchCallModel'
        termination_reason:
          type: string
          default: ''
        error:
          $ref: '#/components/schemas/type_:ConversationHistoryErrorCommonModel'
        warnings:
          type: array
          items:
            type: string
        main_language:
          type: string
        rag_usage:
          $ref: '#/components/schemas/type_:ConversationHistoryRagUsageCommonModel'
        text_only:
          type: boolean
          default: false
        features_usage:
          $ref: '#/components/schemas/type_:FeaturesUsageCommonModel'
        eleven_assistant:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryElevenAssistantCommonModel
        initiator_id:
          type: string
        conversation_initiation_source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
        conversation_initiation_source_version:
          type: string
        timezone:
          type: string
        async_metadata:
          $ref: '#/components/schemas/type_:AsyncConversationMetadata'
        whatsapp:
          $ref: '#/components/schemas/type_:WhatsAppConversationInfo'
        agent_created_from:
          $ref: '#/components/schemas/type_:AgentDefinitionSource'
        agent_last_updated_from:
          $ref: '#/components/schemas/type_:AgentDefinitionSource'
      required:
        - start_time_unix_secs
        - call_duration_secs
    type_:EvaluationSuccessResult:
      type: string
      enum:
        - value: success
        - value: failure
        - value: unknown
    type_:ConversationHistoryEvaluationCriteriaResultCommonModel:
      type: object
      properties:
        criteria_id:
          type: string
        result:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        rationale:
          type: string
      required:
        - criteria_id
        - result
        - rationale
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:DataCollectionResultCommonModel:
      type: object
      properties:
        data_collection_id:
          type: string
        value:
          description: Any type
        json_schema:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        rationale:
          type: string
      required:
        - data_collection_id
        - rationale
    type_:ConversationHistoryAnalysisCommonModel:
      type: object
      properties:
        evaluation_criteria_results:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryEvaluationCriteriaResultCommonModel
        data_collection_results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:DataCollectionResultCommonModel'
        evaluation_criteria_results_list:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryEvaluationCriteriaResultCommonModel
        data_collection_results_list:
          type: array
          items:
            $ref: '#/components/schemas/type_:DataCollectionResultCommonModel'
        call_successful:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        transcript_summary:
          type: string
        call_summary_title:
          type: string
      required:
        - call_successful
        - transcript_summary
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestOutputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestOutput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestOutputDynamicVariablesValue
    type_:GetConversationResponseModel:
      type: object
      properties:
        agent_id:
          type: string
        agent_name:
          type: string
        conversation_id:
          type: string
        status:
          $ref: '#/components/schemas/type_:GetConversationResponseModelStatus'
        user_id:
          type: string
        branch_id:
          type: string
        version_id:
          type: string
          description: The ID of the agent version used for this conversation
        transcript:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        metadata:
          $ref: '#/components/schemas/type_:ConversationHistoryMetadataCommonModel'
        analysis:
          $ref: '#/components/schemas/type_:ConversationHistoryAnalysisCommonModel'
        conversation_initiation_client_data:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataRequestOutput
        has_audio:
          type: boolean
        has_user_audio:
          type: boolean
        has_response_audio:
          type: boolean
      required:
        - agent_id
        - conversation_id
        - status
        - transcript
        - metadata
        - has_audio
        - has_user_audio
        - has_response_audio

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.get("123");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.get(
    conversation_id="123"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversations/123"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversations/123")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/conversations/123")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/conversations/123');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversations/123");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversations/123")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete conversation

DELETE https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}

Delete a particular conversation

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Conversation
  version: endpoint_conversationalAi/conversations.delete
paths:
  /v1/convai/conversations/{conversation_id}:
    delete:
      operationId: delete
      summary: Delete Conversation
      description: Delete a particular conversation
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
      parameters:
        - name: conversation_id
          in: path
          description: The id of the conversation you're taking the action on.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.delete("21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.delete(
    conversation_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get conversation audio

GET https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/audio

Get the audio recording of a particular conversation

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/get-audio

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Conversation Audio
  version: endpoint_conversationalAi/conversations/audio.get
paths:
  /v1/convai/conversations/{conversation_id}/audio:
    get:
      operationId: get
      summary: Get Conversation Audio
      description: Get the audio recording of a particular conversation
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
          - subpackage_conversationalAi/conversations/audio
      parameters:
        - name: conversation_id
          in: path
          description: The id of the conversation you're taking the action on.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.audio.get("21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.audio.get(
    conversation_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("xi-api-key", "sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["xi-api-key"] = 'sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio")
  .header("xi-api-key", "sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'xi-api-key' => 'sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio");
var request = new RestRequest(Method.GET);
request.AddHeader("xi-api-key", "sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "xi-api-key": "sk-4f8b7c9d2e3a4b5c9d0e1f2a3b4c5d6e",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/audio")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get signed URL

GET https://api.elevenlabs.io/v1/convai/conversation/get-signed-url

Get a signed url to start a conversation with an agent with an agent that requires authorization

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/get-signed-url

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Signed Url
  version: endpoint_conversationalAi/conversations.get_signed_url
paths:
  /v1/convai/conversation/get-signed-url:
    get:
      operationId: get-signed-url
      summary: Get Signed Url
      description: >-
        Get a signed url to start a conversation with an agent with an agent
        that requires authorization
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
      parameters:
        - name: agent_id
          in: query
          description: The id of the agent you're taking the action on.
          required: true
          schema:
            type: string
        - name: include_conversation_id
          in: query
          description: >-
            Whether to include a conversation_id with the response. If included,
            the conversation_signature cannot be used again.
          required: false
          schema:
            type: boolean
            default: false
        - name: branch_id
          in: query
          description: The ID of the branch to use
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ConversationSignedUrlResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ConversationSignedUrlResponseModel:
      type: object
      properties:
        signed_url:
          type: string
      required:
        - signed_url

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.getSignedUrl({
        agentId: "21m00Tcm4TlvDq8ikWAM",
        includeConversationId: true,
        branchId: "branch_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.get_signed_url(
    agent_id="21m00Tcm4TlvDq8ikWAM",
    include_conversation_id=True,
    branch_id="branch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=21m00Tcm4TlvDq8ikWAM&include_conversation_id=true&branch_id=branch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get conversation token

GET https://api.elevenlabs.io/v1/convai/conversation/token

Get a WebRTC session token for real-time communication.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/get-webrtc-token

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: >-
    Get a webrtc token to start a conversation with an agent that requires
    authorization
  version: endpoint_conversationalAi/conversations.get_webrtc_token
paths:
  /v1/convai/conversation/token:
    get:
      operationId: get-webrtc-token
      summary: >-
        Get a webrtc token to start a conversation with an agent that requires
        authorization
      description: Get a WebRTC session token for real-time communication.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
      parameters:
        - name: agent_id
          in: query
          description: The id of the agent you're taking the action on.
          required: true
          schema:
            type: string
        - name: participant_name
          in: query
          description: >-
            Optional custom participant name. If not provided, user ID will be
            used
          required: false
          schema:
            type: string
        - name: branch_id
          in: query
          description: The ID of the branch to use
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:TokenResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:TokenResponseModel:
      type: object
      properties:
        token:
          type: string
      required:
        - token

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.getWebrtcToken({
        agentId: "21m00Tcm4TlvDq8ikWAM",
        participantName: "participant_name",
        branchId: "branch_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.get_webrtc_token(
    agent_id="21m00Tcm4TlvDq8ikWAM",
    participant_name="participant_name",
    branch_id="branch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=21m00Tcm4TlvDq8ikWAM&participant_name=participant_name&branch_id=branch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Send conversation feedback

POST https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/feedback
Content-Type: application/json

Send the feedback for the given conversation

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Send Conversation Feedback
  version: endpoint_conversationalAi/conversations/feedback.create
paths:
  /v1/convai/conversations/{conversation_id}/feedback:
    post:
      operationId: create
      summary: Send Conversation Feedback
      description: Send the feedback for the given conversation
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/conversations
          - subpackage_conversationalAi/conversations/feedback
      parameters:
        - name: conversation_id
          in: path
          description: The id of the conversation you're taking the action on.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                feedback:
                  $ref: '#/components/schemas/type_:UserFeedbackScore'
                  description: >-
                    Either 'like' or 'dislike' to indicate the feedback for the
                    conversation.
components:
  schemas:
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.conversations.feedback.create("21m00Tcm4TlvDq8ikWAM", {
        feedback: "like",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.conversations.feedback.create(
    conversation_id="21m00Tcm4TlvDq8ikWAM",
    feedback="like"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback"

	payload := strings.NewReader("{\n  \"feedback\": \"like\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"feedback\": \"like\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback")
  .header("Content-Type", "application/json")
  .body("{\n  \"feedback\": \"like\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback', [
  'body' => '{
  "feedback": "like"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"feedback\": \"like\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["feedback": "like"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/conversations/21m00Tcm4TlvDq8ikWAM/feedback")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List tools

GET https://api.elevenlabs.io/v1/convai/tools

Get all available tools in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Tools
  version: endpoint_conversationalAi/tools.list
paths:
  /v1/convai/tools:
    get:
      operationId: list
      summary: Get Tools
      description: Get all available tools in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: search
          in: query
          description: >-
            If specified, the endpoint returns only tools whose names start with
            this string.
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: >-
            How many documents to return at maximum. Can not exceed 100,
            defaults to 30.
          required: false
          schema:
            type: integer
        - name: show_only_owned_documents
          in: query
          description: >-
            If set to true, the endpoint will return only tools owned by you
            (and not shared from somebody else).
          required: false
          schema:
            type: boolean
            default: false
        - name: types
          in: query
          description: If present, the endpoint will return only tools of the given types.
          required: false
          schema:
            $ref: '#/components/schemas/type_:ToolTypeFilter'
        - name: sort_direction
          in: query
          description: The direction to sort the results
          required: false
          schema:
            $ref: '#/components/schemas/type_:SortDirection'
        - name: sort_by
          in: query
          description: The field to sort the results by
          required: false
          schema:
            $ref: '#/components/schemas/type_:ToolSortBy'
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ToolsResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ToolTypeFilter:
      type: string
      enum:
        - value: webhook
        - value: client
        - value: api_integration_webhook
    type_:SortDirection:
      type: string
      enum:
        - value: asc
        - value: desc
    type_:ToolSortBy:
      type: string
      enum:
        - value: name
        - value: created_at
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolResponseModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:ToolUsageStatsResponseModel:
      type: object
      properties:
        total_calls:
          type: integer
          default: 0
          description: The total number of calls to the tool
        avg_latency_secs:
          type: number
          format: double
      required:
        - avg_latency_secs
    type_:ToolResponseModel:
      type: object
      properties:
        id:
          type: string
        tool_config:
          $ref: '#/components/schemas/type_:ToolResponseModelToolConfig'
          description: The type of tool
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
        usage_stats:
          $ref: '#/components/schemas/type_:ToolUsageStatsResponseModel'
      required:
        - id
        - tool_config
        - access_info
        - usage_stats
    type_:ToolsResponseModel:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:ToolResponseModel'
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - tools
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.list({
        search: "search",
        pageSize: 1,
        showOnlyOwnedDocuments: true,
        sortDirection: "asc",
        sortBy: "name",
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.list(
    search="search",
    page_size=1,
    show_only_owned_documents=True,
    sort_direction="asc",
    sort_by="name",
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools?search=search&page_size=1&show_only_owned_documents=true&sort_direction=asc&sort_by=name&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get tool

GET https://api.elevenlabs.io/v1/convai/tools/{tool_id}

Get tool that is available in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Tool
  version: endpoint_conversationalAi/tools.get
paths:
  /v1/convai/tools/{tool_id}:
    get:
      operationId: get
      summary: Get Tool
      description: Get tool that is available in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: tool_id
          in: path
          description: ID of the requested tool.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ToolResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolResponseModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:ToolUsageStatsResponseModel:
      type: object
      properties:
        total_calls:
          type: integer
          default: 0
          description: The total number of calls to the tool
        avg_latency_secs:
          type: number
          format: double
      required:
        - avg_latency_secs
    type_:ToolResponseModel:
      type: object
      properties:
        id:
          type: string
        tool_config:
          $ref: '#/components/schemas/type_:ToolResponseModelToolConfig'
          description: The type of tool
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
        usage_stats:
          $ref: '#/components/schemas/type_:ToolUsageStatsResponseModel'
      required:
        - id
        - tool_config
        - access_info
        - usage_stats

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.get("tool_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.get(
    tool_id="tool_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools/tool_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools/tool_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/tools/tool_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/tools/tool_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools/tool_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools/tool_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create tool

POST https://api.elevenlabs.io/v1/convai/tools
Content-Type: application/json

Add a new tool to the available tools in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Add Tool
  version: endpoint_conversationalAi/tools.create
paths:
  /v1/convai/tools:
    post:
      operationId: create
      summary: Add Tool
      description: Add a new tool to the available tools in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ToolResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        description: A tool that an agent can provide to LLM.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_:ToolRequestModel'
components:
  schemas:
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolRequestModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ToolRequestModel:
      type: object
      properties:
        tool_config:
          $ref: '#/components/schemas/type_:ToolRequestModelToolConfig'
          description: Configuration for the tool
      required:
        - tool_config
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolResponseModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:ToolUsageStatsResponseModel:
      type: object
      properties:
        total_calls:
          type: integer
          default: 0
          description: The total number of calls to the tool
        avg_latency_secs:
          type: number
          format: double
      required:
        - avg_latency_secs
    type_:ToolResponseModel:
      type: object
      properties:
        id:
          type: string
        tool_config:
          $ref: '#/components/schemas/type_:ToolResponseModelToolConfig'
          description: The type of tool
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
        usage_stats:
          $ref: '#/components/schemas/type_:ToolUsageStatsResponseModel'
      required:
        - id
        - tool_config
        - access_info
        - usage_stats

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.create({
        toolConfig: {
            type: "client",
            description: "description",
            name: "name",
            expectsResponse: false,
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.create(
    tool_config={
        "type": "client",
        "description": "description",
        "name": "name",
        "expects_response": False
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools"

	payload := strings.NewReader("{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/tools")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/tools', [
  'body' => '{
  "tool_config": {
    "type": "client",
    "description": "description",
    "name": "name",
    "expects_response": false
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["tool_config": [
    "type": "client",
    "description": "description",
    "name": "name",
    "expects_response": false
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update tool

PATCH https://api.elevenlabs.io/v1/convai/tools/{tool_id}
Content-Type: application/json

Update tool that is available in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Tool
  version: endpoint_conversationalAi/tools.update
paths:
  /v1/convai/tools/{tool_id}:
    patch:
      operationId: update
      summary: Update Tool
      description: Update tool that is available in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: tool_id
          in: path
          description: ID of the requested tool.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ToolResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        description: A tool that an agent can provide to LLM.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_:ToolRequestModel'
components:
  schemas:
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolRequestModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ToolRequestModel:
      type: object
      properties:
        tool_config:
          $ref: '#/components/schemas/type_:ToolRequestModelToolConfig'
          description: Configuration for the tool
      required:
        - tool_config
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:ToolResponseModelToolConfig:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - type: stringLiteral
                  value: system
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:ToolUsageStatsResponseModel:
      type: object
      properties:
        total_calls:
          type: integer
          default: 0
          description: The total number of calls to the tool
        avg_latency_secs:
          type: number
          format: double
      required:
        - avg_latency_secs
    type_:ToolResponseModel:
      type: object
      properties:
        id:
          type: string
        tool_config:
          $ref: '#/components/schemas/type_:ToolResponseModelToolConfig'
          description: The type of tool
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
        usage_stats:
          $ref: '#/components/schemas/type_:ToolUsageStatsResponseModel'
      required:
        - id
        - tool_config
        - access_info
        - usage_stats

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.update("tool_id", {
        toolConfig: {
            type: "client",
            description: "description",
            name: "name",
            expectsResponse: false,
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.update(
    tool_id="tool_id",
    tool_config={
        "type": "client",
        "description": "description",
        "name": "name",
        "expects_response": False
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools/tool_id"

	payload := strings.NewReader("{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools/tool_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/tools/tool_id")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/tools/tool_id', [
  'body' => '{
  "tool_config": {
    "type": "client",
    "description": "description",
    "name": "name",
    "expects_response": false
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools/tool_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tool_config\": {\n    \"type\": \"client\",\n    \"description\": \"description\",\n    \"name\": \"name\",\n    \"expects_response\": false\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["tool_config": [
    "type": "client",
    "description": "description",
    "name": "name",
    "expects_response": false
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools/tool_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete tool

DELETE https://api.elevenlabs.io/v1/convai/tools/{tool_id}

Delete tool from the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Tool
  version: endpoint_conversationalAi/tools.delete
paths:
  /v1/convai/tools/{tool_id}:
    delete:
      operationId: delete
      summary: Delete Tool
      description: Delete tool from the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: tool_id
          in: path
          description: ID of the requested tool.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.delete("tool_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.delete(
    tool_id="tool_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools/tool_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools/tool_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/tools/tool_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/tools/tool_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools/tool_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools/tool_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get dependent agents

GET https://api.elevenlabs.io/v1/convai/tools/{tool_id}/dependent-agents

Get a list of agents depending on this tool

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/get-dependent-agents

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Dependent Agents List
  version: endpoint_conversationalAi/tools.get_dependent_agents
paths:
  /v1/convai/tools/{tool_id}/dependent-agents:
    get:
      operationId: get-dependent-agents
      summary: Get Dependent Agents List
      description: Get a list of agents depending on this tool
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tools
      parameters:
        - name: tool_id
          in: path
          description: ID of the requested tool.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: >-
            How many documents to return at maximum. Can not exceed 100,
            defaults to 30.
          required: false
          schema:
            type: integer
            default: 30
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetToolDependentAgentsResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:GetToolDependentAgentsResponseModelAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetToolDependentAgentsResponseModel:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:GetToolDependentAgentsResponseModelAgentsItem
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - agents
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tools.getDependentAgents("tool_id", {
        cursor: "cursor",
        pageSize: 1,
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tools.get_dependent_agents(
    tool_id="tool_id",
    cursor="cursor",
    page_size=1
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/tools/tool_id/dependent-agents?cursor=cursor&page_size=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List knowledge base documents

GET https://api.elevenlabs.io/v1/convai/knowledge-base

Get a list of available knowledge base documents

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Knowledge Base List
  version: endpoint_conversationalAi/knowledgeBase.list
paths:
  /v1/convai/knowledge-base:
    get:
      operationId: list
      summary: Get Knowledge Base List
      description: Get a list of available knowledge base documents
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
      parameters:
        - name: page_size
          in: query
          description: >-
            How many documents to return at maximum. Can not exceed 100,
            defaults to 30.
          required: false
          schema:
            type: integer
            default: 30
        - name: search
          in: query
          description: >-
            If specified, the endpoint returns only such knowledge base
            documents whose names start with this string.
          required: false
          schema:
            type: string
        - name: show_only_owned_documents
          in: query
          description: >-
            If set to true, the endpoint will return only documents owned by you
            (and not shared from somebody else).
          required: false
          schema:
            type: boolean
            default: false
        - name: types
          in: query
          description: >-
            If present, the endpoint will return only documents of the given
            types.
          required: false
          schema:
            $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
        - name: parent_folder_id
          in: query
          description: >-
            If set, the endpoint will return only documents that are direct
            children of the given folder.
          required: false
          schema:
            type: string
        - name: ancestor_folder_id
          in: query
          description: >-
            If set, the endpoint will return only documents that are descendants
            of the given folder.
          required: false
          schema:
            type: string
        - name: folders_first
          in: query
          description: Whether folders should be returned first in the list of documents.
          required: false
          schema:
            type: boolean
            default: false
        - name: sort_direction
          in: query
          description: The direction to sort the results
          required: false
          schema:
            $ref: '#/components/schemas/type_:SortDirection'
        - name: sort_by
          in: query
          description: The field to sort the results by
          required: false
          schema:
            $ref: '#/components/schemas/type_:KnowledgeBaseSortBy'
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetKnowledgeBaseListResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:SortDirection:
      type: string
      enum:
        - value: asc
        - value: desc
    type_:KnowledgeBaseSortBy:
      type: string
      enum:
        - value: name
        - value: created_at
        - value: updated_at
        - value: size
    type_:KnowledgeBaseDocumentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
        last_updated_at_unix_secs:
          type: integer
        size_bytes:
          type: integer
      required:
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - size_bytes
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:GetKnowledgeBaseSummaryFileResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryFolderResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryTextResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryUrlResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseListResponseModelDocumentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: 'Discriminator value: file'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryFileResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
        - type: object
          properties:
            type:
              type: string
              enum:
                - folder
              description: 'Discriminator value: folder'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryFolderResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
            children_count:
              type: integer
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
            - children_count
        - type: object
          properties:
            type:
              type: string
              enum:
                - text
              description: 'Discriminator value: text'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryTextResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryUrlResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
            url:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
            - url
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseListResponseModel:
      type: object
      properties:
        documents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:GetKnowledgeBaseListResponseModelDocumentsItem
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - documents
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.list({
        pageSize: 1,
        search: "search",
        showOnlyOwnedDocuments: true,
        parentFolderId: "parent_folder_id",
        ancestorFolderId: "ancestor_folder_id",
        foldersFirst: true,
        sortDirection: "asc",
        sortBy: "name",
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.list(
    page_size=1,
    search="search",
    show_only_owned_documents=True,
    parent_folder_id="parent_folder_id",
    ancestor_folder_id="ancestor_folder_id",
    folders_first=True,
    sort_direction="asc",
    sort_by="name",
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base?page_size=1&search=search&show_only_owned_documents=true&parent_folder_id=parent_folder_id&ancestor_folder_id=ancestor_folder_id&folders_first=true&sort_direction=asc&sort_by=name&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete knowledge base document

DELETE https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}

Delete a document from the knowledge base

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Knowledge Base Document
  version: endpoint_conversationalAi/knowledgeBase/documents.delete
paths:
  /v1/convai/knowledge-base/{documentation_id}:
    delete:
      operationId: delete
      summary: Delete Knowledge Base Document
      description: Delete a document from the knowledge base
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: force
          in: query
          description: >-
            If set to true, the document will be deleted regardless of whether
            it is used by any agents and it will be deleted from the dependent
            agents.
          required: false
          schema:
            type: boolean
            default: false
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.delete("21m00Tcm4TlvDq8ikWAM", {
        force: true,
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.delete(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    force=True
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?force=true")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get knowledge base document

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}

Get details about a specific documentation making up the agent's knowledge base

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-document

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Documentation From Knowledge Base
  version: endpoint_conversationalAi/knowledgeBase/documents.get
paths:
  /v1/convai/knowledge-base/{documentation_id}:
    get:
      operationId: get
      summary: Get Documentation From Knowledge Base
      description: >-
        Get details about a specific documentation making up the agent's
        knowledge base
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            default: ''
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_conversationalAi/knowledgeBase/documents:DocumentsGetResponse
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseDocumentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
        last_updated_at_unix_secs:
          type: integer
        size_bytes:
          type: integer
      required:
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - size_bytes
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:KnowledgeBaseFolderPathSegmentResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
    type_conversationalAi/knowledgeBase/documents:DocumentsGetResponse:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            url:
              type: string
            extracted_inner_html:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - url
            - extracted_inner_html
        - type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: 'Discriminator value: file'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            extracted_inner_html:
              type: string
            filename:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - extracted_inner_html
            - filename
        - type: object
          properties:
            type:
              type: string
              enum:
                - text
              description: 'Discriminator value: text'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            extracted_inner_html:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - extracted_inner_html
        - type: object
          properties:
            type:
              type: string
              enum:
                - folder
              description: 'Discriminator value: folder'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            children_count:
              type: integer
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - children_count
      discriminator:
        propertyName: type

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.get("21m00Tcm4TlvDq8ikWAM", {
        agentId: "agent_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.get(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM?agent_id=agent_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update knowledge base document

PATCH https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}
Content-Type: application/json

Update the name of a document

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Document
  version: endpoint_conversationalAi/knowledgeBase/documents.update
paths:
  /v1/convai/knowledge-base/{documentation_id}:
    patch:
      operationId: update
      summary: Update Document
      description: Update the name of a document
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_conversationalAi/knowledgeBase/documents:DocumentsUpdateResponse
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A custom, human-readable name for the document.
              required:
                - name
components:
  schemas:
    type_:KnowledgeBaseDocumentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
        last_updated_at_unix_secs:
          type: integer
        size_bytes:
          type: integer
      required:
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - size_bytes
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:KnowledgeBaseFolderPathSegmentResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
    type_conversationalAi/knowledgeBase/documents:DocumentsUpdateResponse:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            url:
              type: string
            extracted_inner_html:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - url
            - extracted_inner_html
        - type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: 'Discriminator value: file'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            extracted_inner_html:
              type: string
            filename:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - extracted_inner_html
            - filename
        - type: object
          properties:
            type:
              type: string
              enum:
                - text
              description: 'Discriminator value: text'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            extracted_inner_html:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - extracted_inner_html
        - type: object
          properties:
            type:
              type: string
              enum:
                - folder
              description: 'Discriminator value: folder'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            children_count:
              type: integer
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - children_count
      discriminator:
        propertyName: type

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.update("21m00Tcm4TlvDq8ikWAM", {
        name: "name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.update(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    name="name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM"

	payload := strings.NewReader("{\n  \"name\": \"name\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM', [
  'body' => '{
  "name": "name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["name": "name"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create knowledge base document from URL

POST https://api.elevenlabs.io/v1/convai/knowledge-base/url
Content-Type: application/json

Create a knowledge base document generated by scraping the given webpage.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/create-from-url

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Url Document
  version: endpoint_conversationalAi/knowledgeBase/documents.create_from_url
paths:
  /v1/convai/knowledge-base/url:
    post:
      operationId: create-from-url
      summary: Create Url Document
      description: >-
        Create a knowledge base document generated by scraping the given
        webpage.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AddKnowledgeBaseResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: >-
                    URL to a page of documentation that the agent will have
                    access to in order to interact with users.
                name:
                  type: string
                  description: A custom, human-readable name for the document.
                parent_folder_id:
                  type: string
                  description: >-
                    If set, the created document or folder will be placed inside
                    the given folder.
              required:
                - url
components:
  schemas:
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:AddKnowledgeBaseResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_path:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
          description: >-
            The folder path segments leading to this entity, from root to parent
            folder.
      required:
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.createFromUrl({
        url: "url",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.create_from_url(
    url="url"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/url"

	payload := strings.NewReader("{\n  \"url\": \"url\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"url\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/url")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"url\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/url', [
  'body' => '{
  "url": "url"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/url");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"url\": \"url\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["url": "url"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/url")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create knowledge base document from text

POST https://api.elevenlabs.io/v1/convai/knowledge-base/text
Content-Type: application/json

Create a knowledge base document containing the provided text.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/create-from-text

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Text Document
  version: endpoint_conversationalAi/knowledgeBase/documents.create_from_text
paths:
  /v1/convai/knowledge-base/text:
    post:
      operationId: create-from-text
      summary: Create Text Document
      description: Create a knowledge base document containing the provided text.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AddKnowledgeBaseResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Text content to be added to the knowledge base.
                name:
                  type: string
                  description: A custom, human-readable name for the document.
                parent_folder_id:
                  type: string
                  description: >-
                    If set, the created document or folder will be placed inside
                    the given folder.
              required:
                - text
components:
  schemas:
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:AddKnowledgeBaseResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_path:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
          description: >-
            The folder path segments leading to this entity, from root to parent
            folder.
      required:
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.createFromText({
        text: "text",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.create_from_text(
    text="text"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/text"

	payload := strings.NewReader("{\n  \"text\": \"text\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/text")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"text\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/text")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"text\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/text', [
  'body' => '{
  "text": "text"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/text");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"text\": \"text\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["text": "text"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/text")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create knowledge base document from file

POST https://api.elevenlabs.io/v1/convai/knowledge-base/file
Content-Type: multipart/form-data

Create a knowledge base document generated form the uploaded file.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/create-from-file

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create File Document
  version: endpoint_conversationalAi/knowledgeBase/documents.create_from_file
paths:
  /v1/convai/knowledge-base/file:
    post:
      operationId: create-from-file
      summary: Create File Document
      description: Create a knowledge base document generated form the uploaded file.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AddKnowledgeBaseResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    Documentation that the agent will have access to in order to
                    interact with users.
                name:
                  type: string
                  description: A custom, human-readable name for the document.
                parent_folder_id:
                  type: string
                  description: >-
                    If set, the created document or folder will be placed inside
                    the given folder.
              required:
                - file
components:
  schemas:
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:AddKnowledgeBaseResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_path:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
          description: >-
            The folder path segments leading to this entity, from root to parent
            folder.
      required:
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.createFromFile({});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.create_from_file()

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/file"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"parent_folder_id\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"parent_folder_id\"\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/file")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"parent_folder_id\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/file', [
  'multipart' => [
    [
        'name' => 'file',
        'filename' => '<file1>',
        'contents' => null
    ]
  ]
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/file");
var request = new RestRequest(Method.POST);
request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"name\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"parent_folder_id\"\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "multipart/form-data; boundary=---011000010111000001101001"]
let parameters = [
  [
    "name": "file",
    "fileName": "<file1>"
  ],
  [
    "name": "name",
    "value": 
  ],
  [
    "name": "parent_folder_id",
    "value": 
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/file")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get document content

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/content

Get the entire content of a document from the knowledge base

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-content

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Document Content
  version: endpoint_conversationalAi/knowledgeBase/documents.get_content
paths:
  /v1/convai/knowledge-base/{documentation_id}/content:
    get:
      operationId: get-content
      summary: Get Document Content
      description: Get the entire content of a document from the knowledge base
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.getContent("21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.get_content(
    documentation_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/content")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get document chunk

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/chunk/{chunk_id}

Get details about a specific documentation part used by RAG.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-chunk

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Documentation Chunk From Knowledge Base
  version: endpoint_conversationalAi/knowledgeBase/documents/chunk.get
paths:
  /v1/convai/knowledge-base/{documentation_id}/chunk/{chunk_id}:
    get:
      operationId: get
      summary: Get Documentation Chunk From Knowledge Base
      description: Get details about a specific documentation part used by RAG.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
          - subpackage_conversationalAi/knowledgeBase/documents/chunk
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: chunk_id
          in: path
          description: The id of a document RAG chunk from the knowledge base.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseDocumentChunkResponseModel
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseDocumentChunkResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        content:
          type: string
      required:
        - id
        - name
        - content

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.chunk.get("21m00Tcm4TlvDq8ikWAM", "chunk_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.chunk.get(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    chunk_id="chunk_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/chunk/chunk_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get source file URL

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/source-file-url

Get a signed URL to download the original source file of a file-type document from the knowledge base

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-source-file-url

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Document Source File Url
  version: endpoint_conversationalAi/knowledgeBase/documents.get_source_file_url
paths:
  /v1/convai/knowledge-base/{documentation_id}/source-file-url:
    get:
      operationId: get-source-file-url
      summary: Get Document Source File Url
      description: >-
        Get a signed URL to download the original source file of a file-type
        document from the knowledge base
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseSourceFileUrlResponseModel
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseSourceFileUrlResponseModel:
      type: object
      properties:
        signed_url:
          type: string
          description: Signed URL to download the source file directly
      required:
        - signed_url

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.getSourceFileUrl("21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.get_source_file_url(
    documentation_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/source-file-url")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create folder

POST https://api.elevenlabs.io/v1/convai/knowledge-base/folder
Content-Type: application/json

Create a folder used for grouping documents together.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/create-folder

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Folder
  version: endpoint_conversationalAi/knowledgeBase/documents.create_folder
paths:
  /v1/convai/knowledge-base/folder:
    post:
      operationId: create-folder
      summary: Create Folder
      description: Create a folder used for grouping documents together.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AddKnowledgeBaseResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A custom, human-readable name for the document.
                parent_folder_id:
                  type: string
                  description: >-
                    If set, the created document or folder will be placed inside
                    the given folder.
              required:
                - name
components:
  schemas:
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:AddKnowledgeBaseResponseModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_path:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
          description: >-
            The folder path segments leading to this entity, from root to parent
            folder.
      required:
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.createFolder({
        name: "name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.create_folder(
    name="name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/folder"

	payload := strings.NewReader("{\n  \"name\": \"name\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/folder")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/folder")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/folder', [
  'body' => '{
  "name": "name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/folder");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["name": "name"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/folder")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Move document

POST https://api.elevenlabs.io/v1/convai/knowledge-base/{document_id}/move
Content-Type: application/json

Moves the entity from one folder to another.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/move-document

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Move Entity To Folder
  version: endpoint_conversationalAi/knowledgeBase/documents.move
paths:
  /v1/convai/knowledge-base/{document_id}/move:
    post:
      operationId: move
      summary: Move Entity To Folder
      description: Moves the entity from one folder to another.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: document_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                move_to:
                  type: string
                  description: >-
                    The folder to move the entities to. If not set, the entities
                    will be moved to the root folder.

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.move("21m00Tcm4TlvDq8ikWAM", {
        moveTo: "folder_9a8b7c6d5e4f3g2h1i0j",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.move(
    document_id="21m00Tcm4TlvDq8ikWAM",
    move_to="folder_9a8b7c6d5e4f3g2h1i0j"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move"

	payload := strings.NewReader("{\n  \"move_to\": \"folder_9a8b7c6d5e4f3g2h1i0j\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"move_to\": \"folder_9a8b7c6d5e4f3g2h1i0j\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move")
  .header("Content-Type", "application/json")
  .body("{\n  \"move_to\": \"folder_9a8b7c6d5e4f3g2h1i0j\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move', [
  'body' => '{
  "move_to": "folder_9a8b7c6d5e4f3g2h1i0j"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"move_to\": \"folder_9a8b7c6d5e4f3g2h1i0j\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["move_to": "folder_9a8b7c6d5e4f3g2h1i0j"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/move")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Bulk move documents

POST https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move
Content-Type: application/json

Moves multiple entities from one folder to another.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/bulk-move

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Bulk Move Entities To Folder
  version: endpoint_conversationalAi/knowledgeBase/documents.bulk_move
paths:
  /v1/convai/knowledge-base/bulk-move:
    post:
      operationId: bulk-move
      summary: Bulk Move Entities To Folder
      description: Moves multiple entities from one folder to another.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                document_ids:
                  type: array
                  items:
                    type: string
                  description: The ids of documents or folders from the knowledge base.
                move_to:
                  type: string
                  description: >-
                    The folder to move the entities to. If not set, the entities
                    will be moved to the root folder.
              required:
                - document_ids

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.bulkMove({
        documentIds: [
            "21m00Tcm4TlvDq8ikWAM",
            "31m00Tcm4TlvDq8ikWBM",
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.bulk_move(
    document_ids=[
        "21m00Tcm4TlvDq8ikWAM",
        "31m00Tcm4TlvDq8ikWBM"
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move"

	payload := strings.NewReader("{\n  \"document_ids\": [\n    \"21m00Tcm4TlvDq8ikWAM\",\n    \"31m00Tcm4TlvDq8ikWBM\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_ids\": [\n    \"21m00Tcm4TlvDq8ikWAM\",\n    \"31m00Tcm4TlvDq8ikWBM\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_ids\": [\n    \"21m00Tcm4TlvDq8ikWAM\",\n    \"31m00Tcm4TlvDq8ikWBM\"\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move', [
  'body' => '{
  "document_ids": [
    "21m00Tcm4TlvDq8ikWAM",
    "31m00Tcm4TlvDq8ikWBM"
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"document_ids\": [\n    \"21m00Tcm4TlvDq8ikWAM\",\n    \"31m00Tcm4TlvDq8ikWBM\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["document_ids": ["21m00Tcm4TlvDq8ikWAM", "31m00Tcm4TlvDq8ikWBM"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/bulk-move")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Compute RAG index

POST https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/rag-index
Content-Type: application/json

In case the document is not RAG indexed, it triggers rag indexing task, otherwise it just returns the current status.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/compute-rag-index

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Compute Rag Index.
  version: endpoint_conversationalAi/knowledgeBase/document.compute_rag_index
paths:
  /v1/convai/knowledge-base/{documentation_id}/rag-index:
    post:
      operationId: compute-rag-index
      summary: Compute Rag Index.
      description: >-
        In case the document is not RAG indexed, it triggers rag indexing task,
        otherwise it just returns the current status.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/document
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:RagDocumentIndexResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  $ref: '#/components/schemas/type_:EmbeddingModelEnum'
              required:
                - model
components:
  schemas:
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagIndexStatus:
      type: string
      enum:
        - value: created
        - value: processing
        - value: failed
        - value: succeeded
        - value: rag_limit_exceeded
        - value: document_too_small
        - value: cannot_index_folder
    type_:RagDocumentIndexUsage:
      type: object
      properties:
        used_bytes:
          type: integer
      required:
        - used_bytes
    type_:RagDocumentIndexResponseModel:
      type: object
      properties:
        id:
          type: string
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        status:
          $ref: '#/components/schemas/type_:RagIndexStatus'
        progress_percentage:
          type: number
          format: double
        document_model_index_usage:
          $ref: '#/components/schemas/type_:RagDocumentIndexUsage'
      required:
        - id
        - model
        - status
        - progress_percentage
        - document_model_index_usage

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.document.computeRagIndex("21m00Tcm4TlvDq8ikWAM", {
        model: "e5_mistral_7b_instruct",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.document.compute_rag_index(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    model="e5_mistral_7b_instruct"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index"

	payload := strings.NewReader("{\n  \"model\": \"e5_mistral_7b_instruct\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"e5_mistral_7b_instruct\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"e5_mistral_7b_instruct\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index', [
  'body' => '{
  "model": "e5_mistral_7b_instruct"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"e5_mistral_7b_instruct\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["model": "e5_mistral_7b_instruct"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get RAG index

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/rag-index

Provides information about all RAG indexes of the specified knowledgebase document.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-rag-index

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Rag Indexes Of The Specified Knowledgebase Document.
  version: endpoint_conversationalAi.get_document_rag_indexes
paths:
  /v1/convai/knowledge-base/{documentation_id}/rag-index:
    get:
      operationId: get-document-rag-indexes
      summary: Get Rag Indexes Of The Specified Knowledgebase Document.
      description: >-
        Provides information about all RAG indexes of the specified
        knowledgebase document.
      tags:
        - - subpackage_conversationalAi
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:RagDocumentIndexesResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagIndexStatus:
      type: string
      enum:
        - value: created
        - value: processing
        - value: failed
        - value: succeeded
        - value: rag_limit_exceeded
        - value: document_too_small
        - value: cannot_index_folder
    type_:RagDocumentIndexUsage:
      type: object
      properties:
        used_bytes:
          type: integer
      required:
        - used_bytes
    type_:RagDocumentIndexResponseModel:
      type: object
      properties:
        id:
          type: string
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        status:
          $ref: '#/components/schemas/type_:RagIndexStatus'
        progress_percentage:
          type: number
          format: double
        document_model_index_usage:
          $ref: '#/components/schemas/type_:RagDocumentIndexUsage'
      required:
        - id
        - model
        - status
        - progress_percentage
        - document_model_index_usage
    type_:RagDocumentIndexesResponseModel:
      type: object
      properties:
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagDocumentIndexResponseModel'
      required:
        - indexes

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.getDocumentRagIndexes("21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.get_document_rag_indexes(
    documentation_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get RAG index overview

GET https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index

Provides total size and other information of RAG indexes used by knowledgebase documents

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/rag-index-overview

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Rag Index Overview.
  version: endpoint_conversationalAi.rag_index_overview
paths:
  /v1/convai/knowledge-base/rag-index:
    get:
      operationId: rag-index-overview
      summary: Get Rag Index Overview.
      description: >-
        Provides total size and other information of RAG indexes used by
        knowledgebase documents
      tags:
        - - subpackage_conversationalAi
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:RagIndexOverviewResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagIndexOverviewEmbeddingModelResponseModel:
      type: object
      properties:
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        used_bytes:
          type: integer
      required:
        - model
        - used_bytes
    type_:RagIndexOverviewResponseModel:
      type: object
      properties:
        total_used_bytes:
          type: integer
        total_max_bytes:
          type: integer
        models:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:RagIndexOverviewEmbeddingModelResponseModel
      required:
        - total_used_bytes
        - total_max_bytes
        - models

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.ragIndexOverview();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.rag_index_overview()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Compute RAG index in batch

POST https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index
Content-Type: application/json

Retrieves and/or creates RAG indexes for multiple knowledge base documents in a single request.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/compute-rag-index-batch

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Compute Rag Indexes In Batch
  version: endpoint_conversationalAi/knowledgeBase.get_or_create_rag_indexes
paths:
  /v1/convai/knowledge-base/rag-index:
    post:
      operationId: get-or-create-rag-indexes
      summary: Compute Rag Indexes In Batch
      description: >-
        Retrieves and/or creates RAG indexes for multiple knowledge base
        documents in a single request.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: >-
                    #/components/schemas/type_conversationalAi/knowledgeBase:KnowledgeBaseGetOrCreateRagIndexesResponseValue
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:GetOrCreateRagIndexRequestModel'
                  description: List of requested RAG indexes.
              required:
                - items
components:
  schemas:
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:GetOrCreateRagIndexRequestModel:
      type: object
      properties:
        document_id:
          type: string
          description: ID of the knowledgebase document for which to retrieve the index
        create_if_missing:
          type: boolean
          description: Whether to create the RAG index if it does not exist
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
          description: Embedding model to use for the RAG index
      required:
        - document_id
        - create_if_missing
        - model
    type_:RagIndexStatus:
      type: string
      enum:
        - value: created
        - value: processing
        - value: failed
        - value: succeeded
        - value: rag_limit_exceeded
        - value: document_too_small
        - value: cannot_index_folder
    type_:RagDocumentIndexUsage:
      type: object
      properties:
        used_bytes:
          type: integer
      required:
        - used_bytes
    type_:RagDocumentIndexResponseModel:
      type: object
      properties:
        id:
          type: string
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        status:
          $ref: '#/components/schemas/type_:RagIndexStatus'
        progress_percentage:
          type: number
          format: double
        document_model_index_usage:
          $ref: '#/components/schemas/type_:RagDocumentIndexUsage'
      required:
        - id
        - model
        - status
        - progress_percentage
        - document_model_index_usage
    type_conversationalAi/knowledgeBase:KnowledgeBaseGetOrCreateRagIndexesResponseValue:
      oneOf:
        - type: object
          properties:
            status:
              type: string
              enum:
                - success
              description: 'Discriminator value: success'
            data:
              $ref: '#/components/schemas/type_:RagDocumentIndexResponseModel'
          required:
            - status
            - data
        - type: object
          properties:
            status:
              type: string
              enum:
                - failure
              description: 'Discriminator value: failure'
            error_code:
              type: integer
            error_status:
              type: string
            error_message:
              type: string
          required:
            - status
            - error_code
            - error_status
            - error_message
      discriminator:
        propertyName: status

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.getOrCreateRagIndexes({
        items: [
            {
                documentId: "document_id",
                createIfMissing: true,
                model: "e5_mistral_7b_instruct",
            },
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.get_or_create_rag_indexes(
    items=[
        {
            "document_id": "document_id",
            "create_if_missing": True,
            "model": "e5_mistral_7b_instruct"
        }
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"document_id\": \"document_id\",\n      \"create_if_missing\": true,\n      \"model\": \"e5_mistral_7b_instruct\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"document_id\": \"document_id\",\n      \"create_if_missing\": true,\n      \"model\": \"e5_mistral_7b_instruct\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"document_id\": \"document_id\",\n      \"create_if_missing\": true,\n      \"model\": \"e5_mistral_7b_instruct\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index', [
  'body' => '{
  "items": [
    {
      "document_id": "document_id",
      "create_if_missing": true,
      "model": "e5_mistral_7b_instruct"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"items\": [\n    {\n      \"document_id\": \"document_id\",\n      \"create_if_missing\": true,\n      \"model\": \"e5_mistral_7b_instruct\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["items": [
    [
      "document_id": "document_id",
      "create_if_missing": true,
      "model": "e5_mistral_7b_instruct"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/rag-index")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete RAG index

DELETE https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/rag-index/{rag_index_id}

Delete RAG index for the knowledgebase document.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/delete-rag-index

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Rag Index.
  version: endpoint_conversationalAi.delete_document_rag_index
paths:
  /v1/convai/knowledge-base/{documentation_id}/rag-index/{rag_index_id}:
    delete:
      operationId: delete-document-rag-index
      summary: Delete Rag Index.
      description: Delete RAG index for the knowledgebase document.
      tags:
        - - subpackage_conversationalAi
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: rag_index_id
          in: path
          description: The id of RAG index of document from the knowledge base.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:RagDocumentIndexResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagIndexStatus:
      type: string
      enum:
        - value: created
        - value: processing
        - value: failed
        - value: succeeded
        - value: rag_limit_exceeded
        - value: document_too_small
        - value: cannot_index_folder
    type_:RagDocumentIndexUsage:
      type: object
      properties:
        used_bytes:
          type: integer
      required:
        - used_bytes
    type_:RagDocumentIndexResponseModel:
      type: object
      properties:
        id:
          type: string
        model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        status:
          $ref: '#/components/schemas/type_:RagIndexStatus'
        progress_percentage:
          type: number
          format: double
        document_model_index_usage:
          $ref: '#/components/schemas/type_:RagDocumentIndexUsage'
      required:
        - id
        - model
        - status
        - progress_percentage
        - document_model_index_usage

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.deleteDocumentRagIndex("21m00Tcm4TlvDq8ikWAM", "21m00Tcm4TlvDq8ikWAM");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.delete_document_rag_index(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    rag_index_id="21m00Tcm4TlvDq8ikWAM"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("DELETE", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/rag-index/21m00Tcm4TlvDq8ikWAM")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get dependent agents

GET https://api.elevenlabs.io/v1/convai/knowledge-base/{documentation_id}/dependent-agents

Get a list of agents depending on this knowledge base document

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-agents

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Dependent Agents List
  version: endpoint_conversationalAi/knowledgeBase/documents.get_agents
paths:
  /v1/convai/knowledge-base/{documentation_id}/dependent-agents:
    get:
      operationId: get-agents
      summary: Get Dependent Agents List
      description: Get a list of agents depending on this knowledge base document
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
      parameters:
        - name: documentation_id
          in: path
          description: >-
            The id of a document from the knowledge base. This is returned on
            document addition.
          required: true
          schema:
            type: string
        - name: dependent_type
          in: query
          description: Type of dependent agents to return.
          required: false
          schema:
            $ref: '#/components/schemas/type_:KnowledgeBaseDependentType'
        - name: page_size
          in: query
          description: >-
            How many documents to return at maximum. Can not exceed 100,
            defaults to 30.
          required: false
          schema:
            type: integer
            default: 30
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseDependentAgentsResponseModel
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseDependentType:
      type: string
      enum:
        - value: direct
        - value: transitive
        - value: all
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:GetKnowledgeBaseDependentAgentsResponseModelAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseDependentAgentsResponseModel:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:GetKnowledgeBaseDependentAgentsResponseModelAgentsItem
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - agents
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.getAgents("21m00Tcm4TlvDq8ikWAM", {
        dependentType: "direct",
        pageSize: 1,
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.get_agents(
    documentation_id="21m00Tcm4TlvDq8ikWAM",
    dependent_type="direct",
    page_size=1,
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/21m00Tcm4TlvDq8ikWAM/dependent-agents?dependent_type=direct&page_size=1&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get knowledge base size

GET https://api.elevenlabs.io/v1/convai/agent/{agent_id}/knowledge-base/size

Returns the number of pages in the agent's knowledge base.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/size

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Returns The Size Of The Agent'S Knowledge Base
  version: endpoint_conversationalAi/agents/knowledgeBase.size
paths:
  /v1/convai/agent/{agent_id}/knowledge-base/size:
    get:
      operationId: size
      summary: Returns The Size Of The Agent'S Knowledge Base
      description: Returns the number of pages in the agent's knowledge base.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/knowledgeBase
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:GetAgentKnowledgebaseSizeResponseModel
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetAgentKnowledgebaseSizeResponseModel:
      type: object
      properties:
        number_of_pages:
          type: number
          format: double
      required:
        - number_of_pages

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.knowledgeBase.size("agent_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.knowledge_base.size(
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent/agent_id/knowledge-base/size")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get knowledge base summaries

GET https://api.elevenlabs.io/v1/convai/knowledge-base/summaries

Gets multiple knowledge base document summaries by their IDs.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-summaries

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Knowledge Base Summaries By Ids
  version: endpoint_conversationalAi/knowledgeBase/documents/summaries.get
paths:
  /v1/convai/knowledge-base/summaries:
    get:
      operationId: get
      summary: Get Knowledge Base Summaries By Ids
      description: Gets multiple knowledge base document summaries by their IDs.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/knowledgeBase
          - subpackage_conversationalAi/knowledgeBase/documents
          - subpackage_conversationalAi/knowledgeBase/documents/summaries
      parameters:
        - name: document_ids
          in: query
          description: The ids of knowledge base documents.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: >-
                    #/components/schemas/type_conversationalAi/knowledgeBase/documents/summaries:SummariesGetResponseValue
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:KnowledgeBaseDocumentMetadataResponseModel:
      type: object
      properties:
        created_at_unix_secs:
          type: integer
        last_updated_at_unix_secs:
          type: integer
        size_bytes:
          type: integer
      required:
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - size_bytes
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:GetKnowledgeBaseSummaryFileResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryFolderResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryTextResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:GetKnowledgeBaseSummaryUrlResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:KnowledgeBaseSummaryBatchSuccessfulResponseModelData:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: 'Discriminator value: file'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryFileResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
        - type: object
          properties:
            type:
              type: string
              enum:
                - folder
              description: 'Discriminator value: folder'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryFolderResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
            children_count:
              type: integer
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
            - children_count
        - type: object
          properties:
            type:
              type: string
              enum:
                - text
              description: 'Discriminator value: text'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryTextResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            id:
              type: string
            name:
              type: string
            metadata:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseDocumentMetadataResponseModel
            supported_usages:
              type: array
              items:
                $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
            access_info:
              $ref: '#/components/schemas/type_:ResourceAccessInfo'
            folder_parent_id:
              type: string
              description: >-
                The ID of the parent folder, or null if the document is at the
                root level.
            folder_path:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:KnowledgeBaseFolderPathSegmentSummaryResponseModel
              description: >-
                The folder path segments leading to this entity, from root to
                parent folder.
            dependent_agents:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:GetKnowledgeBaseSummaryUrlResponseModelDependentAgentsItem
              description: >-
                This field is deprecated and will be removed in the future, use
                the separate endpoint to get dependent agents instead.
            url:
              type: string
          required:
            - type
            - id
            - name
            - metadata
            - supported_usages
            - access_info
            - dependent_agents
            - url
      discriminator:
        propertyName: type
    type_conversationalAi/knowledgeBase/documents/summaries:SummariesGetResponseValue:
      oneOf:
        - type: object
          properties:
            status:
              type: string
              enum:
                - success
              description: 'Discriminator value: success'
            data:
              $ref: >-
                #/components/schemas/type_:KnowledgeBaseSummaryBatchSuccessfulResponseModelData
          required:
            - status
            - data
        - type: object
          properties:
            status:
              type: string
              enum:
                - failure
              description: 'Discriminator value: failure'
            error_code:
              type: integer
            error_status:
              type: string
            error_message:
              type: string
          required:
            - status
            - error_code
            - error_status
            - error_message
      discriminator:
        propertyName: status

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.knowledgeBase.documents.summaries.get({});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.knowledge_base.documents.summaries.get()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/knowledge-base/summaries"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/knowledge-base/summaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/knowledge-base/summaries")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/knowledge-base/summaries');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/knowledge-base/summaries");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/knowledge-base/summaries")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List tests

GET https://api.elevenlabs.io/v1/convai/agent-testing

Lists all agent response tests with pagination support and optional search filtering.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Agent Response Tests
  version: endpoint_conversationalAi/tests.list
paths:
  /v1/convai/agent-testing:
    get:
      operationId: list
      summary: List Agent Response Tests
      description: >-
        Lists all agent response tests with pagination support and optional
        search filtering.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: >-
            How many Tests to return at maximum. Can not exceed 100, defaults to
            30.
          required: false
          schema:
            type: integer
            default: 30
        - name: search
          in: query
          description: Search query to filter tests by name.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetTestsPageResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:UnitTestSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the test
        name:
          type: string
          description: Name of the test
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the test
        created_at_unix_secs:
          type: integer
          description: Creation time of the test in unix seconds
        last_updated_at_unix_secs:
          type: integer
          description: Last update time of the test in unix seconds
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
          description: Type of the test
      required:
        - id
        - name
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - type
    type_:GetTestsPageResponseModel:
      type: object
      properties:
        tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestSummaryResponseModel'
        next_cursor:
          type: string
        has_more:
          type: boolean
      required:
        - tests
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.list({
        cursor: "cursor",
        pageSize: 1,
        search: "search",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.list(
    cursor="cursor",
    page_size=1,
    search="search"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing?cursor=cursor&page_size=1&search=search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get test

GET https://api.elevenlabs.io/v1/convai/agent-testing/{test_id}

Gets an agent response test by ID.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Response Test By Id
  version: endpoint_conversationalAi/tests.get
paths:
  /v1/convai/agent-testing/{test_id}:
    get:
      operationId: get
      summary: Get Agent Response Test By Id
      description: Gets an agent response test by ID.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: test_id
          in: path
          description: The id of a chat response test. This is returned on test creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetUnitTestResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:AgentSuccessfulResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: success
      required:
        - response
        - type
    type_:AgentFailureResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: failure
      required:
        - response
        - type
    type_:UnitTestToolCallParameterEval:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - anything
              description: 'Discriminator value: anything'
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - exact
              description: 'Discriminator value: exact'
            expected_value:
              type: string
              description: The exact string value that the parameter must match.
          required:
            - type
            - expected_value
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            description:
              type: string
              description: A description of the evaluation strategy to use for the test.
          required:
            - type
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - regex
              description: 'Discriminator value: regex'
            pattern:
              type: string
              description: A regex pattern to match the agent's response against.
          required:
            - type
            - pattern
      discriminator:
        propertyName: type
    type_:UnitTestToolCallParameter:
      type: object
      properties:
        eval:
          $ref: '#/components/schemas/type_:UnitTestToolCallParameterEval'
        path:
          type: string
      required:
        - eval
        - path
    type_:ReferencedToolCommonModelType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: workflow
        - value: api_integration_webhook
    type_:ReferencedToolCommonModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool
        type:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModelType'
          description: The type of the tool
      required:
        - id
        - type
    type_:UnitTestWorkflowNodeTransitionEvaluationNodeId:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: node_id
        agent_id:
          type: string
          description: The ID of the agent whose workflow contains the target node.
        target_node_id:
          type: string
          description: The ID of the workflow node that the agent should transition to.
      required:
        - agent_id
        - target_node_id
    type_:UnitTestToolCallEvaluationModelOutput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_:GetUnitTestResponseModelDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:TestFromConversationMetadataOutput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
      required:
        - conversation_id
        - agent_id
    type_:GetUnitTestResponseModel:
      type: object
      properties:
        chat_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        success_condition:
          type: string
          description: >-
            A prompt that evaluates whether the agent's response is successful.
            Should return True or False.
        success_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            successful
        failure_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentFailureResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            failures
        tool_call_parameters:
          $ref: '#/components/schemas/type_:UnitTestToolCallEvaluationModelOutput'
          description: >-
            How to evaluate the agent's tool call (if any). If empty, the tool
            call is not evaluated.
        check_any_tool_matches:
          type: boolean
          description: >-
            If set to True this test will pass if any tool call returned by the
            LLM matches the criteria. Otherwise it will fail if more than one
            tool is returned by the agent.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:GetUnitTestResponseModelDynamicVariablesValue
          description: Dynamic variables to replace in the agent config during testing
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
        from_conversation_metadata:
          $ref: '#/components/schemas/type_:TestFromConversationMetadataOutput'
          description: >-
            Metadata of a conversation this test was created from (if
            applicable).
        id:
          type: string
        name:
          type: string
      required:
        - chat_history
        - success_condition
        - success_examples
        - failure_examples
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.get("TeaqRRdTcIfIu2i7BYfT");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.get(
    test_id="TeaqRRdTcIfIu2i7BYfT"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create test

POST https://api.elevenlabs.io/v1/convai/agent-testing/create
Content-Type: application/json

Creates a new agent response test.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Agent Response Test
  version: endpoint_conversationalAi/tests.create
paths:
  /v1/convai/agent-testing/create:
    post:
      operationId: create
      summary: Create Agent Response Test
      description: Creates a new agent response test.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreateUnitTestResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                chat_history:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
                success_condition:
                  type: string
                  description: >-
                    A prompt that evaluates whether the agent's response is
                    successful. Should return True or False.
                success_examples:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
                  description: >-
                    Non-empty list of example responses that should be
                    considered successful
                failure_examples:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:AgentFailureResponseExample'
                  description: >-
                    Non-empty list of example responses that should be
                    considered failures
                tool_call_parameters:
                  $ref: >-
                    #/components/schemas/type_:UnitTestToolCallEvaluationModelInput
                  description: >-
                    How to evaluate the agent's tool call (if any). If empty,
                    the tool call is not evaluated.
                check_any_tool_matches:
                  type: boolean
                  description: >-
                    If set to True this test will pass if any tool call returned
                    by the LLM matches the criteria. Otherwise it will fail if
                    more than one tool is returned by the agent.
                dynamic_variables:
                  type: object
                  additionalProperties:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/tests:CreateUnitTestRequestDynamicVariablesValue
                  description: >-
                    Dynamic variables to replace in the agent config during
                    testing
                type:
                  $ref: '#/components/schemas/type_:UnitTestCommonModelType'
                from_conversation_metadata:
                  $ref: '#/components/schemas/type_:TestFromConversationMetadataInput'
                  description: >-
                    Metadata of a conversation this test was created from (if
                    applicable).
                name:
                  type: string
              required:
                - chat_history
                - success_condition
                - success_examples
                - failure_examples
                - name
components:
  schemas:
    type_:ConversationHistoryTranscriptCommonModelInputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelInputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:WorkflowToolResponseModelInputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelInputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelInput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/type_:WorkflowToolResponseModelInputStepsItem'
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelInput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageInput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelInputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelInput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageInput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:AgentSuccessfulResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: success
      required:
        - response
        - type
    type_:AgentFailureResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: failure
      required:
        - response
        - type
    type_:UnitTestToolCallParameterEval:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - anything
              description: 'Discriminator value: anything'
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - exact
              description: 'Discriminator value: exact'
            expected_value:
              type: string
              description: The exact string value that the parameter must match.
          required:
            - type
            - expected_value
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            description:
              type: string
              description: A description of the evaluation strategy to use for the test.
          required:
            - type
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - regex
              description: 'Discriminator value: regex'
            pattern:
              type: string
              description: A regex pattern to match the agent's response against.
          required:
            - type
            - pattern
      discriminator:
        propertyName: type
    type_:UnitTestToolCallParameter:
      type: object
      properties:
        eval:
          $ref: '#/components/schemas/type_:UnitTestToolCallParameterEval'
        path:
          type: string
      required:
        - eval
        - path
    type_:ReferencedToolCommonModelType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: workflow
        - value: api_integration_webhook
    type_:ReferencedToolCommonModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool
        type:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModelType'
          description: The type of the tool
      required:
        - id
        - type
    type_:UnitTestWorkflowNodeTransitionEvaluationNodeId:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: node_id
        agent_id:
          type: string
          description: The ID of the agent whose workflow contains the target node.
        target_node_id:
          type: string
          description: The ID of the workflow node that the agent should transition to.
      required:
        - agent_id
        - target_node_id
    type_:UnitTestToolCallEvaluationModelInput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_conversationalAi/tests:CreateUnitTestRequestDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:TestFromConversationMetadataInput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
      required:
        - conversation_id
        - agent_id
    type_:CreateUnitTestResponseModel:
      type: object
      properties:
        id:
          type: string
      required:
        - id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.create({
        chatHistory: [
            {
                role: "user",
                timeInCallSecs: 1,
            },
        ],
        successCondition: "success_condition",
        successExamples: [
            {
                response: "response",
                type: "success",
            },
        ],
        failureExamples: [
            {
                response: "response",
                type: "failure",
            },
        ],
        name: "name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.create(
    chat_history=[
        {
            "role": "user",
            "time_in_call_secs": 1
        }
    ],
    success_condition="success_condition",
    success_examples=[
        {
            "response": "response",
            "type": "success"
        }
    ],
    failure_examples=[
        {
            "response": "response",
            "type": "failure"
        }
    ],
    name="name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing/create"

	payload := strings.NewReader("{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agent-testing/create")
  .header("Content-Type", "application/json")
  .body("{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agent-testing/create', [
  'body' => '{
  "chat_history": [
    {
      "role": "user",
      "time_in_call_secs": 1
    }
  ],
  "success_condition": "success_condition",
  "success_examples": [
    {
      "response": "response",
      "type": "success"
    }
  ],
  "failure_examples": [
    {
      "response": "response",
      "type": "failure"
    }
  ],
  "name": "name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing/create");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "chat_history": [
    [
      "role": "user",
      "time_in_call_secs": 1
    ]
  ],
  "success_condition": "success_condition",
  "success_examples": [
    [
      "response": "response",
      "type": "success"
    ]
  ],
  "failure_examples": [
    [
      "response": "response",
      "type": "failure"
    ]
  ],
  "name": "name"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing/create")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update test

PUT https://api.elevenlabs.io/v1/convai/agent-testing/{test_id}
Content-Type: application/json

Updates an agent response test by ID.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Agent Response Test
  version: endpoint_conversationalAi/tests.update
paths:
  /v1/convai/agent-testing/{test_id}:
    put:
      operationId: update
      summary: Update Agent Response Test
      description: Updates an agent response test by ID.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: test_id
          in: path
          description: The id of a chat response test. This is returned on test creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetUnitTestResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                chat_history:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
                success_condition:
                  type: string
                  description: >-
                    A prompt that evaluates whether the agent's response is
                    successful. Should return True or False.
                success_examples:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
                  description: >-
                    Non-empty list of example responses that should be
                    considered successful
                failure_examples:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:AgentFailureResponseExample'
                  description: >-
                    Non-empty list of example responses that should be
                    considered failures
                tool_call_parameters:
                  $ref: >-
                    #/components/schemas/type_:UnitTestToolCallEvaluationModelInput
                  description: >-
                    How to evaluate the agent's tool call (if any). If empty,
                    the tool call is not evaluated.
                check_any_tool_matches:
                  type: boolean
                  description: >-
                    If set to True this test will pass if any tool call returned
                    by the LLM matches the criteria. Otherwise it will fail if
                    more than one tool is returned by the agent.
                dynamic_variables:
                  type: object
                  additionalProperties:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/tests:UpdateUnitTestRequestDynamicVariablesValue
                  description: >-
                    Dynamic variables to replace in the agent config during
                    testing
                type:
                  $ref: '#/components/schemas/type_:UnitTestCommonModelType'
                from_conversation_metadata:
                  $ref: '#/components/schemas/type_:TestFromConversationMetadataInput'
                  description: >-
                    Metadata of a conversation this test was created from (if
                    applicable).
                name:
                  type: string
              required:
                - chat_history
                - success_condition
                - success_examples
                - failure_examples
                - name
components:
  schemas:
    type_:ConversationHistoryTranscriptCommonModelInputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - &ref_4
                  type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - &ref_5
                  type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - &ref_6
                  type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - &ref_7
                  type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - &ref_8
                  type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - &ref_9
                  type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - &ref_10
                  type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - &ref_11
                  type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - &ref_12
                  type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelInputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:WorkflowToolResponseModelInputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelInputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelInput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/type_:WorkflowToolResponseModelInputStepsItem'
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelInput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelInput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelInput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageInput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelInputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelInput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelInput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageInput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:AgentSuccessfulResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: success
      required:
        - response
        - type
    type_:AgentFailureResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: failure
      required:
        - response
        - type
    type_:UnitTestToolCallParameterEval:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - anything
              description: 'Discriminator value: anything'
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - exact
              description: 'Discriminator value: exact'
            expected_value:
              type: string
              description: The exact string value that the parameter must match.
          required:
            - type
            - expected_value
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            description:
              type: string
              description: A description of the evaluation strategy to use for the test.
          required:
            - type
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - regex
              description: 'Discriminator value: regex'
            pattern:
              type: string
              description: A regex pattern to match the agent's response against.
          required:
            - type
            - pattern
      discriminator:
        propertyName: type
    type_:UnitTestToolCallParameter:
      type: object
      properties:
        eval:
          $ref: '#/components/schemas/type_:UnitTestToolCallParameterEval'
        path:
          type: string
      required:
        - eval
        - path
    type_:ReferencedToolCommonModelType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: workflow
        - value: api_integration_webhook
    type_:ReferencedToolCommonModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool
        type:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModelType'
          description: The type of the tool
      required:
        - id
        - type
    type_:UnitTestWorkflowNodeTransitionEvaluationNodeId:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: node_id
        agent_id:
          type: string
          description: The ID of the agent whose workflow contains the target node.
        target_node_id:
          type: string
          description: The ID of the workflow node that the agent should transition to.
      required:
        - agent_id
        - target_node_id
    type_:UnitTestToolCallEvaluationModelInput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_conversationalAi/tests:UpdateUnitTestRequestDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:TestFromConversationMetadataInput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelInput
      required:
        - conversation_id
        - agent_id
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - *ref_1
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - *ref_2
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - *ref_3
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - *ref_4
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - *ref_5
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - *ref_6
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - *ref_7
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - *ref_8
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - *ref_9
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - *ref_10
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - *ref_11
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - *ref_12
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:UnitTestToolCallEvaluationModelOutput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_:GetUnitTestResponseModelDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:TestFromConversationMetadataOutput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
      required:
        - conversation_id
        - agent_id
    type_:GetUnitTestResponseModel:
      type: object
      properties:
        chat_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        success_condition:
          type: string
          description: >-
            A prompt that evaluates whether the agent's response is successful.
            Should return True or False.
        success_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            successful
        failure_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentFailureResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            failures
        tool_call_parameters:
          $ref: '#/components/schemas/type_:UnitTestToolCallEvaluationModelOutput'
          description: >-
            How to evaluate the agent's tool call (if any). If empty, the tool
            call is not evaluated.
        check_any_tool_matches:
          type: boolean
          description: >-
            If set to True this test will pass if any tool call returned by the
            LLM matches the criteria. Otherwise it will fail if more than one
            tool is returned by the agent.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:GetUnitTestResponseModelDynamicVariablesValue
          description: Dynamic variables to replace in the agent config during testing
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
        from_conversation_metadata:
          $ref: '#/components/schemas/type_:TestFromConversationMetadataOutput'
          description: >-
            Metadata of a conversation this test was created from (if
            applicable).
        id:
          type: string
        name:
          type: string
      required:
        - chat_history
        - success_condition
        - success_examples
        - failure_examples
        - id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.update("TeaqRRdTcIfIu2i7BYfT", {
        chatHistory: [
            {
                role: "user",
                timeInCallSecs: 1,
            },
        ],
        successCondition: "success_condition",
        successExamples: [
            {
                response: "response",
                type: "success",
            },
        ],
        failureExamples: [
            {
                response: "response",
                type: "failure",
            },
        ],
        name: "name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.update(
    test_id="TeaqRRdTcIfIu2i7BYfT",
    chat_history=[
        {
            "role": "user",
            "time_in_call_secs": 1
        }
    ],
    success_condition="success_condition",
    success_examples=[
        {
            "response": "response",
            "type": "success"
        }
    ],
    failure_examples=[
        {
            "response": "response",
            "type": "failure"
        }
    ],
    name="name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT"

	payload := strings.NewReader("{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")
  .header("Content-Type", "application/json")
  .body("{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT', [
  'body' => '{
  "chat_history": [
    {
      "role": "user",
      "time_in_call_secs": 1
    }
  ],
  "success_condition": "success_condition",
  "success_examples": [
    {
      "response": "response",
      "type": "success"
    }
  ],
  "failure_examples": [
    {
      "response": "response",
      "type": "failure"
    }
  ],
  "name": "name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"chat_history\": [\n    {\n      \"role\": \"user\",\n      \"time_in_call_secs\": 1\n    }\n  ],\n  \"success_condition\": \"success_condition\",\n  \"success_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"success\"\n    }\n  ],\n  \"failure_examples\": [\n    {\n      \"response\": \"response\",\n      \"type\": \"failure\"\n    }\n  ],\n  \"name\": \"name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "chat_history": [
    [
      "role": "user",
      "time_in_call_secs": 1
    ]
  ],
  "success_condition": "success_condition",
  "success_examples": [
    [
      "response": "response",
      "type": "success"
    ]
  ],
  "failure_examples": [
    [
      "response": "response",
      "type": "failure"
    ]
  ],
  "name": "name"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete test

DELETE https://api.elevenlabs.io/v1/convai/agent-testing/{test_id}

Deletes an agent response test by ID.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Agent Response Test
  version: endpoint_conversationalAi/tests.delete
paths:
  /v1/convai/agent-testing/{test_id}:
    delete:
      operationId: delete
      summary: Delete Agent Response Test
      description: Deletes an agent response test by ID.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: test_id
          in: path
          description: The id of a chat response test. This is returned on test creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.delete("TeaqRRdTcIfIu2i7BYfT");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.delete(
    test_id="TeaqRRdTcIfIu2i7BYfT"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get test summaries

POST https://api.elevenlabs.io/v1/convai/agent-testing/summaries
Content-Type: application/json

Gets multiple agent response tests by their IDs. Returns a dictionary mapping test IDs to test summaries.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/summaries

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Response Test Summaries By Ids
  version: endpoint_conversationalAi/tests.summaries
paths:
  /v1/convai/agent-testing/summaries:
    post:
      operationId: summaries
      summary: Get Agent Response Test Summaries By Ids
      description: >-
        Gets multiple agent response tests by their IDs. Returns a dictionary
        mapping test IDs to test summaries.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetTestsSummariesByIdsResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                test_ids:
                  type: array
                  items:
                    type: string
                  description: List of test IDs to fetch. No duplicates allowed.
              required:
                - test_ids
components:
  schemas:
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:UnitTestSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the test
        name:
          type: string
          description: Name of the test
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the test
        created_at_unix_secs:
          type: integer
          description: Creation time of the test in unix seconds
        last_updated_at_unix_secs:
          type: integer
          description: Last update time of the test in unix seconds
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
          description: Type of the test
      required:
        - id
        - name
        - created_at_unix_secs
        - last_updated_at_unix_secs
        - type
    type_:GetTestsSummariesByIdsResponseModel:
      type: object
      properties:
        tests:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:UnitTestSummaryResponseModel'
          description: Dictionary mapping test IDs to their summary information
      required:
        - tests

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.summaries({
        testIds: [
            "test_id_1",
            "test_id_2",
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.summaries(
    test_ids=[
        "test_id_1",
        "test_id_2"
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agent-testing/summaries"

	payload := strings.NewReader("{\n  \"test_ids\": [\n    \"test_id_1\",\n    \"test_id_2\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agent-testing/summaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"test_ids\": [\n    \"test_id_1\",\n    \"test_id_2\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agent-testing/summaries")
  .header("Content-Type", "application/json")
  .body("{\n  \"test_ids\": [\n    \"test_id_1\",\n    \"test_id_2\"\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agent-testing/summaries', [
  'body' => '{
  "test_ids": [
    "test_id_1",
    "test_id_2"
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agent-testing/summaries");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"test_ids\": [\n    \"test_id_1\",\n    \"test_id_2\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["test_ids": ["test_id_1", "test_id_2"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agent-testing/summaries")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Run tests on agent

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/run-tests
Content-Type: application/json

Run selected tests on the agent with provided configuration. If the agent configuration is provided, it will be used to override default agent configuration.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/run-tests

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Run Tests On The Agent
  version: endpoint_conversationalAi/agents.run_tests
paths:
  /v1/convai/agents/{agent_id}/run-tests:
    post:
      operationId: run-tests
      summary: Run Tests On The Agent
      description: >-
        Run selected tests on the agent with provided configuration. If the
        agent configuration is provided, it will be used to override default
        agent configuration.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetTestSuiteInvocationResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tests:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:SingleTestRunRequestModel'
                  description: List of tests to run on the agent
                agent_config_override:
                  $ref: >-
                    #/components/schemas/type_:AdhocAgentConfigOverrideForTestRequestModel
                  description: >-
                    Configuration overrides to use for testing. If not provided,
                    the agent's default configuration will be used.
                branch_id:
                  type: string
                  description: >-
                    ID of the branch to run the tests on. If not provided, the
                    tests will be run on the agent default configuration.
              required:
                - tests
components:
  schemas:
    type_:SingleTestRunRequestModel:
      type: object
      properties:
        test_id:
          type: string
          description: ID of the test to run
        workflow_node_id:
          type: string
          description: >-
            ID of the workflow node to run the test on. If not provided, the
            test will be run on the agent's default workflow node.
      required:
        - test_id
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfig:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfig:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          default: -1
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          default: Hhmmmm...yeah.
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          default: false
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfig:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          default: 7
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          default: -1
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfig'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          default: false
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          default: cjVigY5qzO86Huf0OWal
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          default: 0.5
          description: The stability of generated speech
        speed:
          type: number
          format: double
          default: 1
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          default: 0.8
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          default: 600
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          default: false
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetOutput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfig:
      type: object
      properties: {}
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ConversationalConfig:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfig'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfig'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOutput'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfig'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfig'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfig'
          description: Agent specific configuration
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:EvaluationSettings:
      type: object
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
          description: Individual criteria that the agent should be evaluated against
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigOutputAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetTermsTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:WidgetLanguagePreset:
      type: object
      properties:
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
        terms_translation:
          $ref: '#/components/schemas/type_:WidgetTermsTranslation'
          description: The translation cache for the terms
    type_:WidgetConfig:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigOutputAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language_selector:
          type: boolean
          default: false
          description: Whether to show the language selector
        supports_text_only:
          type: boolean
          default: true
          description: Whether the widget can switch to text only mode
        custom_avatar_path:
          type: string
          description: The custom avatar path
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePreset'
          description: Language presets for the widget
    type_:SoftTimeoutConfigOverrideConfig:
      type: object
      properties:
        message:
          type: boolean
          default: false
          description: Whether to allow overriding the message field.
    type_:TurnConfigOverrideConfig:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:TtsConversationalConfigOverrideConfig:
      type: object
      properties:
        voice_id:
          type: boolean
          default: false
          description: Whether to allow overriding the voice_id field.
        stability:
          type: boolean
          default: false
          description: Whether to allow overriding the stability field.
        speed:
          type: boolean
          default: false
          description: Whether to allow overriding the speed field.
        similarity_boost:
          type: boolean
          default: false
          description: Whether to allow overriding the similarity_boost field.
    type_:ConversationConfigOverrideConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: Whether to allow overriding the text_only field.
    type_:PromptAgentApiModelOverrideConfig:
      type: object
      properties:
        prompt:
          type: boolean
          default: false
          description: Whether to allow overriding the prompt field.
        llm:
          type: boolean
          default: false
          description: Whether to allow overriding the llm field.
        native_mcp_server_ids:
          type: boolean
          default: false
          description: Whether to allow overriding the native_mcp_server_ids field.
    type_:AgentConfigOverrideConfig:
      type: object
      properties:
        first_message:
          type: boolean
          default: false
          description: Whether to allow overriding the first_message field.
        language:
          type: boolean
          default: false
          description: Whether to allow overriding the language field.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationConfigClientOverrideConfigInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigInput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigInput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:AgentWorkspaceOverridesInput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:AttachedTestModel:
      type: object
      properties:
        test_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - test_id
    type_:AgentTestingSettings:
      type: object
      properties:
        attached_tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AttachedTestModel'
          description: List of test IDs that should be run for this agent
    type_:AuthSettings:
      type: object
      properties:
        enable_auth:
          type: boolean
          default: false
          description: >-
            If set to true, starting a conversation with an agent will require a
            signed token
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            A list of hosts that are allowed to start conversations with the
            agent
        require_origin_header:
          type: boolean
          default: false
          description: >-
            When enabled, connections with no origin header will be rejected. If
            the allowlist is empty, this option has no effect.
        shareable_token:
          type: string
          description: >-
            A shareable token that can be used to start a conversation with the
            agent
    type_:AgentCallLimits:
      type: object
      properties:
        agent_concurrency_limit:
          type: integer
          default: -1
          description: >-
            The maximum number of concurrent conversations. -1 indicates that
            there is no maximum
        daily_limit:
          type: integer
          default: 100000
          description: The maximum number of conversations per day
        bursting_enabled:
          type: boolean
          default: true
          description: >-
            Whether to enable bursting. If true, exceeding workspace concurrency
            limit will be allowed up to 3 times the limit. Calls will be charged
            at double rate when exceeding the limit.
    type_:PrivacyConfig:
      type: object
      properties:
        record_voice:
          type: boolean
          default: true
          description: Whether to record the conversation
        retention_days:
          type: integer
          default: -1
          description: >-
            The number of days to retain the conversation. -1 indicates there is
            no retention limit
        delete_transcript_and_pii:
          type: boolean
          default: false
          description: Whether to delete the transcript and PII
        delete_audio:
          type: boolean
          default: false
          description: Whether to delete the audio
        apply_to_existing_conversations:
          type: boolean
          default: false
          description: Whether to apply the privacy settings to existing conversations
        zero_retention_mode:
          type: boolean
          default: false
          description: Whether to enable zero retention mode - no PII data is stored
    type_:AgentPlatformSettingsRequestModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigInput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesInput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_4
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_1
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_2
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_3
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_4
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:AdhocAgentConfigOverrideForTestRequestModel:
      type: object
      properties:
        conversation_config:
          $ref: '#/components/schemas/type_:ConversationalConfig'
        platform_settings:
          $ref: '#/components/schemas/type_:AgentPlatformSettingsRequestModel'
        workflow:
          $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
      required:
        - conversation_config
        - platform_settings
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_5
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_5
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:AgentSuccessfulResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: success
      required:
        - response
        - type
    type_:AgentFailureResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: failure
      required:
        - response
        - type
    type_:UnitTestToolCallParameterEval:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - anything
              description: 'Discriminator value: anything'
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - exact
              description: 'Discriminator value: exact'
            expected_value:
              type: string
              description: The exact string value that the parameter must match.
          required:
            - type
            - expected_value
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            description:
              type: string
              description: A description of the evaluation strategy to use for the test.
          required:
            - type
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - regex
              description: 'Discriminator value: regex'
            pattern:
              type: string
              description: A regex pattern to match the agent's response against.
          required:
            - type
            - pattern
      discriminator:
        propertyName: type
    type_:UnitTestToolCallParameter:
      type: object
      properties:
        eval:
          $ref: '#/components/schemas/type_:UnitTestToolCallParameterEval'
        path:
          type: string
      required:
        - eval
        - path
    type_:ReferencedToolCommonModelType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: workflow
        - value: api_integration_webhook
    type_:ReferencedToolCommonModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool
        type:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModelType'
          description: The type of the tool
      required:
        - id
        - type
    type_:UnitTestWorkflowNodeTransitionEvaluationNodeId:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: node_id
        agent_id:
          type: string
          description: The ID of the agent whose workflow contains the target node.
        target_node_id:
          type: string
          description: The ID of the workflow node that the agent should transition to.
      required:
        - agent_id
        - target_node_id
    type_:UnitTestToolCallEvaluationModelOutput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_:UnitTestCommonModelDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:TestFromConversationMetadataOutput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
      required:
        - conversation_id
        - agent_id
    type_:UnitTestCommonModel:
      type: object
      properties:
        chat_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        success_condition:
          type: string
          description: >-
            A prompt that evaluates whether the agent's response is successful.
            Should return True or False.
        success_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            successful
        failure_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentFailureResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            failures
        tool_call_parameters:
          $ref: '#/components/schemas/type_:UnitTestToolCallEvaluationModelOutput'
          description: >-
            How to evaluate the agent's tool call (if any). If empty, the tool
            call is not evaluated.
        check_any_tool_matches:
          type: boolean
          description: >-
            If set to True this test will pass if any tool call returned by the
            LLM matches the criteria. Otherwise it will fail if more than one
            tool is returned by the agent.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:UnitTestCommonModelDynamicVariablesValue
          description: Dynamic variables to replace in the agent config during testing
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
        from_conversation_metadata:
          $ref: '#/components/schemas/type_:TestFromConversationMetadataOutput'
          description: >-
            Metadata of a conversation this test was created from (if
            applicable).
      required:
        - chat_history
        - success_condition
        - success_examples
        - failure_examples
    type_:TestRunStatus:
      type: string
      enum:
        - value: pending
        - value: passed
        - value: failed
    type_:EvaluationSuccessResult:
      type: string
      enum:
        - value: success
        - value: failure
        - value: unknown
    type_:TestConditionRationaleCommonModel:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
          description: List of individual parameter evaluation messages or reasons
        summary:
          type: string
          default: ''
          description: High-level summary of the evaluation result
    type_:TestConditionResultCommonModel:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        rationale:
          $ref: '#/components/schemas/type_:TestConditionRationaleCommonModel'
      required:
        - result
    type_:TestRunMetadataTestType:
      type: string
      enum:
        - value: llm
        - value: tool_call
      default: llm
    type_:TestRunMetadata:
      type: object
      properties:
        workspace_id:
          type: string
        test_name:
          type: string
        ran_by_user_email:
          type: string
        test_type:
          $ref: '#/components/schemas/type_:TestRunMetadataTestType'
      required:
        - workspace_id
        - test_name
        - ran_by_user_email
    type_:UnitTestRunResponseModel:
      type: object
      properties:
        test_run_id:
          type: string
        test_info:
          $ref: '#/components/schemas/type_:UnitTestCommonModel'
        test_invocation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        status:
          $ref: '#/components/schemas/type_:TestRunStatus'
        agent_responses:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        test_id:
          type: string
        test_name:
          type: string
          default: Unknown Test
        condition_result:
          $ref: '#/components/schemas/type_:TestConditionResultCommonModel'
        last_updated_at_unix:
          type: integer
        metadata:
          $ref: '#/components/schemas/type_:TestRunMetadata'
      required:
        - test_run_id
        - test_invocation_id
        - agent_id
        - status
        - test_id
    type_:GetTestSuiteInvocationResponseModel:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        created_at:
          type: integer
        test_runs:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestRunResponseModel'
      required:
        - id
        - test_runs

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.runTests("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        tests: [
            {
                testId: "test_id",
            },
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.run_tests(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    tests=[
        {
            "test_id": "test_id"
        }
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests"

	payload := strings.NewReader("{\n  \"tests\": [\n    {\n      \"test_id\": \"test_id\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tests\": [\n    {\n      \"test_id\": \"test_id\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests")
  .header("Content-Type", "application/json")
  .body("{\n  \"tests\": [\n    {\n      \"test_id\": \"test_id\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests', [
  'body' => '{
  "tests": [
    {
      "test_id": "test_id"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tests\": [\n    {\n      \"test_id\": \"test_id\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["tests": [["test_id": "test_id"]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/run-tests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get test invocation

GET https://api.elevenlabs.io/v1/convai/test-invocations/{test_invocation_id}

Gets a test invocation by ID.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/test-invocations/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Test Invocation
  version: endpoint_conversationalAi/tests/invocations.get
paths:
  /v1/convai/test-invocations/{test_invocation_id}:
    get:
      operationId: get
      summary: Get Test Invocation
      description: Gets a test invocation by ID.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
          - subpackage_conversationalAi/tests/invocations
      parameters:
        - name: test_invocation_id
          in: path
          description: The id of a test invocation. This is returned when tests are run.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetTestSuiteInvocationResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ConversationHistoryTranscriptCommonModelOutputRole:
      type: string
      enum:
        - value: user
        - value: agent
    type_:AgentMetadata:
      type: object
      properties:
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - agent_id
    type_:ConversationHistoryMultivoiceMessagePartModel:
      type: object
      properties:
        text:
          type: string
        voice_label:
          type: string
        time_in_call_secs:
          type: integer
      required:
        - text
    type_:ConversationHistoryMultivoiceMessageModel:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryMultivoiceMessagePartModel
      required:
        - parts
    type_:ToolType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: mcp
        - value: workflow
        - value: api_integration_webhook
        - value: api_integration_mcp
    type_:ConversationHistoryTranscriptToolCallWebhookDetails:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: webhook
        method:
          type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        path_params:
          type: object
          additionalProperties:
            type: string
        query_params:
          type: object
          additionalProperties:
            type: string
        body:
          type: string
      required:
        - method
        - url
    type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            integration_id:
              type: string
            credential_id:
              type: string
            integration_connection_id:
              type: string
            webhook_details:
              $ref: >-
                #/components/schemas/type_:ConversationHistoryTranscriptToolCallWebhookDetails
          required:
            - type
            - integration_id
            - credential_id
            - integration_connection_id
            - webhook_details
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            parameters:
              type: string
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            mcp_server_id:
              type: string
            mcp_server_name:
              type: string
            integration_type:
              type: string
            parameters:
              type: object
              additionalProperties:
                type: string
            approval_policy:
              type: string
            requires_approval:
              type: boolean
              default: false
            mcp_tool_name:
              type: string
              default: ''
            mcp_tool_description:
              type: string
              default: ''
          required:
            - type
            - mcp_server_id
            - mcp_server_name
            - integration_type
            - approval_policy
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            method:
              type: string
            url:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            path_params:
              type: object
              additionalProperties:
                type: string
            query_params:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
          required:
            - type
            - method
            - url
      discriminator:
        propertyName: type
    type_:ConversationHistoryTranscriptToolCallCommonModelOutput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:ToolType'
        request_id:
          type: string
        tool_name:
          type: string
        params_as_json:
          type: string
        tool_has_been_called:
          type: boolean
        tool_details:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutputToolDetails
      required:
        - request_id
        - tool_name
        - params_as_json
        - tool_has_been_called
    type_:DynamicVariableUpdateCommonModel:
      type: object
      properties:
        variable_name:
          type: string
        old_value:
          type: string
        new_value:
          type: string
        updated_at:
          type: number
          format: double
        tool_name:
          type: string
        tool_request_id:
          type: string
      required:
        - variable_name
        - new_value
        - updated_at
        - tool_name
        - tool_request_id
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType:
      type: string
      enum:
        - value: client
        - value: webhook
        - value: mcp
    type_:ConversationHistoryTranscriptOtherToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModelType
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
    type_:TransferToAgentToolResultSuccessModelBranchInfo:
      oneOf:
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - defaulting_to_main
              description: 'Discriminator value: defaulting_to_main'
            branch_id:
              type: string
          required:
            - branch_reason
            - branch_id
        - type: object
          properties:
            branch_reason:
              type: string
              enum:
                - traffic_split
              description: 'Discriminator value: traffic_split'
            branch_id:
              type: string
            traffic_percentage:
              type: number
              format: double
          required:
            - branch_reason
            - branch_id
            - traffic_percentage
      discriminator:
        propertyName: branch_reason
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult:
      oneOf:
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - end_call_success
              description: 'Discriminator value: end_call_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            message:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - language_detection_success
              description: 'Discriminator value: language_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
            language:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_error
              description: 'Discriminator value: play_dtmf_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - play_dtmf_success
              description: 'Discriminator value: play_dtmf_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            dtmf_tones:
              type: string
            reason:
              type: string
          required:
            - result_type
            - dtmf_tones
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - skip_turn_success
              description: 'Discriminator value: skip_turn_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - testing_tool_result
              description: 'Discriminator value: testing_tool_result'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            reason:
              type: string
              default: Skipping tool call in test mode
          required:
            - result_type
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_error
              description: 'Discriminator value: transfer_to_agent_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            from_agent:
              type: string
            error:
              type: string
          required:
            - result_type
            - from_agent
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_agent_success
              description: 'Discriminator value: transfer_to_agent_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            from_agent:
              type: string
            to_agent:
              type: string
            condition:
              type: string
            delay_ms:
              type: integer
              default: 0
            transfer_message:
              type: string
            enable_transferred_agent_first_message:
              type: boolean
              default: false
            branch_info:
              $ref: >-
                #/components/schemas/type_:TransferToAgentToolResultSuccessModelBranchInfo
          required:
            - result_type
            - from_agent
            - to_agent
            - condition
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_error
              description: 'Discriminator value: transfer_to_number_error'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: error
            error:
              type: string
            details:
              type: string
          required:
            - result_type
            - error
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_sip_success
              description: 'Discriminator value: transfer_to_number_sip_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - transfer_to_number_twilio_success
              description: 'Discriminator value: transfer_to_number_twilio_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            transfer_number:
              type: string
            reason:
              type: string
            client_message:
              type: string
            agent_message:
              type: string
            conference_name:
              type: string
            note:
              type: string
          required:
            - result_type
            - transfer_number
            - agent_message
            - conference_name
        - type: object
          properties:
            result_type:
              type: string
              enum:
                - voicemail_detection_success
              description: 'Discriminator value: voicemail_detection_success'
            status:
              type: string
              enum:
                - type: stringLiteral
                  value: success
            voicemail_message:
              type: string
            reason:
              type: string
          required:
            - result_type
      discriminator:
        propertyName: result_type
    type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: system
        result:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutputResult
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: api_integration_webhook
        integration_id:
          type: string
        credential_id:
          type: string
        integration_connection_id:
          type: string
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
        - integration_id
        - credential_id
        - integration_connection_id
    type_:WorkflowToolNestedToolsStepModelOutputResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:WorkflowToolResponseModelOutputStepsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - edge
              description: 'Discriminator value: edge'
            step_latency_secs:
              type: number
              format: double
            edge_id:
              type: string
            target_node_id:
              type: string
          required:
            - type
            - step_latency_secs
            - edge_id
            - target_node_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - max_iterations_exceeded
              description: 'Discriminator value: max_iterations_exceeded'
            step_latency_secs:
              type: number
              format: double
            max_iterations:
              type: integer
          required:
            - type
            - step_latency_secs
            - max_iterations
        - type: object
          properties:
            type:
              type: string
              enum:
                - nested_tools
              description: 'Discriminator value: nested_tools'
            step_latency_secs:
              type: number
              format: double
            node_id:
              type: string
            requests:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
            results:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowToolNestedToolsStepModelOutputResultsItem
            is_successful:
              type: boolean
          required:
            - type
            - step_latency_secs
            - node_id
            - requests
            - results
            - is_successful
      discriminator:
        propertyName: type
    type_:WorkflowToolResponseModelOutput:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:WorkflowToolResponseModelOutputStepsItem
    type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput:
      type: object
      properties:
        request_id:
          type: string
        tool_name:
          type: string
        result_value:
          type: string
        is_error:
          type: boolean
        tool_has_been_called:
          type: boolean
        tool_latency_secs:
          type: number
          format: double
          default: 0
        error_type:
          type: string
          default: ''
        raw_error_message:
          type: string
          default: ''
        dynamic_variable_updates:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableUpdateCommonModel'
        type:
          type: string
          enum:
            - type: stringLiteral
              value: workflow
        result:
          $ref: '#/components/schemas/type_:WorkflowToolResponseModelOutput'
      required:
        - request_id
        - tool_name
        - result_value
        - is_error
        - tool_has_been_called
        - type
    type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem:
      oneOf:
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptOtherToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptSystemToolResultCommonModelOutput
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptApiIntegrationWebhookToolsResultCommonModel
        - $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptWorkflowToolsResultCommonModelOutput
    type_:UserFeedbackScore:
      type: string
      enum:
        - value: like
        - value: dislike
    type_:UserFeedback:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/type_:UserFeedbackScore'
        time_in_call_secs:
          type: integer
      required:
        - score
        - time_in_call_secs
    type_:MetricRecord:
      type: object
      properties:
        elapsed_time:
          type: number
          format: double
      required:
        - elapsed_time
    type_:ConversationTurnMetrics:
      type: object
      properties:
        metrics:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:MetricRecord'
        convai_asr_provider:
          type: string
        convai_tts_model:
          type: string
    type_:RagChunkMetadata:
      type: object
      properties:
        document_id:
          type: string
        chunk_id:
          type: string
        vector_distance:
          type: number
          format: double
      required:
        - document_id
        - chunk_id
        - vector_distance
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagRetrievalInfo:
      type: object
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/type_:RagChunkMetadata'
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        retrieval_query:
          type: string
        rag_latency_secs:
          type: number
          format: double
      required:
        - chunks
        - embedding_model
        - retrieval_query
        - rag_latency_secs
    type_:LlmTokensCategoryUsage:
      type: object
      properties:
        tokens:
          type: integer
          default: 0
        price:
          type: number
          format: double
          default: 0
    type_:LlmInputOutputTokensUsage:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_read:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        input_cache_write:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
        output_total:
          $ref: '#/components/schemas/type_:LlmTokensCategoryUsage'
    type_:LlmUsageOutput:
      type: object
      properties:
        model_usage:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LlmInputOutputTokensUsage'
    type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium:
      type: string
      enum:
        - value: audio
        - value: text
    type_:ConversationHistoryTranscriptCommonModelOutput:
      type: object
      properties:
        role:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputRole
        agent_metadata:
          $ref: '#/components/schemas/type_:AgentMetadata'
        message:
          type: string
        multivoice_message:
          $ref: '#/components/schemas/type_:ConversationHistoryMultivoiceMessageModel'
        tool_calls:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptToolCallCommonModelOutput
        tool_results:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputToolResultsItem
        feedback:
          $ref: '#/components/schemas/type_:UserFeedback'
        llm_override:
          type: string
        time_in_call_secs:
          type: integer
        conversation_turn_metrics:
          $ref: '#/components/schemas/type_:ConversationTurnMetrics'
        rag_retrieval_info:
          $ref: '#/components/schemas/type_:RagRetrievalInfo'
        llm_usage:
          $ref: '#/components/schemas/type_:LlmUsageOutput'
        interrupted:
          type: boolean
          default: false
        original_message:
          type: string
        source_medium:
          $ref: >-
            #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutputSourceMedium
      required:
        - role
        - time_in_call_secs
    type_:AgentSuccessfulResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: success
      required:
        - response
        - type
    type_:AgentFailureResponseExample:
      type: object
      properties:
        response:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: failure
      required:
        - response
        - type
    type_:UnitTestToolCallParameterEval:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - anything
              description: 'Discriminator value: anything'
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - exact
              description: 'Discriminator value: exact'
            expected_value:
              type: string
              description: The exact string value that the parameter must match.
          required:
            - type
            - expected_value
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            description:
              type: string
              description: A description of the evaluation strategy to use for the test.
          required:
            - type
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - regex
              description: 'Discriminator value: regex'
            pattern:
              type: string
              description: A regex pattern to match the agent's response against.
          required:
            - type
            - pattern
      discriminator:
        propertyName: type
    type_:UnitTestToolCallParameter:
      type: object
      properties:
        eval:
          $ref: '#/components/schemas/type_:UnitTestToolCallParameterEval'
        path:
          type: string
      required:
        - eval
        - path
    type_:ReferencedToolCommonModelType:
      type: string
      enum:
        - value: system
        - value: webhook
        - value: client
        - value: workflow
        - value: api_integration_webhook
    type_:ReferencedToolCommonModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool
        type:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModelType'
          description: The type of the tool
      required:
        - id
        - type
    type_:UnitTestWorkflowNodeTransitionEvaluationNodeId:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: node_id
        agent_id:
          type: string
          description: The ID of the agent whose workflow contains the target node.
        target_node_id:
          type: string
          description: The ID of the workflow node that the agent should transition to.
      required:
        - agent_id
        - target_node_id
    type_:UnitTestToolCallEvaluationModelOutput:
      type: object
      properties:
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestToolCallParameter'
          description: >-
            Parameters to evaluate for the agent's tool call. If empty, the tool
            call parameters are not evaluated.
        referenced_tool:
          $ref: '#/components/schemas/type_:ReferencedToolCommonModel'
          description: The tool to evaluate a call against.
        verify_absence:
          type: boolean
          default: false
          description: Whether to verify that the tool was NOT called.
        workflow_node_transition:
          $ref: >-
            #/components/schemas/type_:UnitTestWorkflowNodeTransitionEvaluationNodeId
          description: >-
            Configuration for testing workflow node transitions. When set, the
            test will verify the agent transitions to the specified workflow
            node.
    type_:UnitTestCommonModelDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:UnitTestCommonModelType:
      type: string
      enum:
        - value: llm
        - value: tool
    type_:TestFromConversationMetadataOutput:
      type: object
      properties:
        conversation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        original_agent_reply:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
      required:
        - conversation_id
        - agent_id
    type_:UnitTestCommonModel:
      type: object
      properties:
        chat_history:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        success_condition:
          type: string
          description: >-
            A prompt that evaluates whether the agent's response is successful.
            Should return True or False.
        success_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentSuccessfulResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            successful
        failure_examples:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentFailureResponseExample'
          description: >-
            Non-empty list of example responses that should be considered
            failures
        tool_call_parameters:
          $ref: '#/components/schemas/type_:UnitTestToolCallEvaluationModelOutput'
          description: >-
            How to evaluate the agent's tool call (if any). If empty, the tool
            call is not evaluated.
        check_any_tool_matches:
          type: boolean
          description: >-
            If set to True this test will pass if any tool call returned by the
            LLM matches the criteria. Otherwise it will fail if more than one
            tool is returned by the agent.
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:UnitTestCommonModelDynamicVariablesValue
          description: Dynamic variables to replace in the agent config during testing
        type:
          $ref: '#/components/schemas/type_:UnitTestCommonModelType'
        from_conversation_metadata:
          $ref: '#/components/schemas/type_:TestFromConversationMetadataOutput'
          description: >-
            Metadata of a conversation this test was created from (if
            applicable).
      required:
        - chat_history
        - success_condition
        - success_examples
        - failure_examples
    type_:TestRunStatus:
      type: string
      enum:
        - value: pending
        - value: passed
        - value: failed
    type_:EvaluationSuccessResult:
      type: string
      enum:
        - value: success
        - value: failure
        - value: unknown
    type_:TestConditionRationaleCommonModel:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
          description: List of individual parameter evaluation messages or reasons
        summary:
          type: string
          default: ''
          description: High-level summary of the evaluation result
    type_:TestConditionResultCommonModel:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/type_:EvaluationSuccessResult'
        rationale:
          $ref: '#/components/schemas/type_:TestConditionRationaleCommonModel'
      required:
        - result
    type_:TestRunMetadataTestType:
      type: string
      enum:
        - value: llm
        - value: tool_call
      default: llm
    type_:TestRunMetadata:
      type: object
      properties:
        workspace_id:
          type: string
        test_name:
          type: string
        ran_by_user_email:
          type: string
        test_type:
          $ref: '#/components/schemas/type_:TestRunMetadataTestType'
      required:
        - workspace_id
        - test_name
        - ran_by_user_email
    type_:UnitTestRunResponseModel:
      type: object
      properties:
        test_run_id:
          type: string
        test_info:
          $ref: '#/components/schemas/type_:UnitTestCommonModel'
        test_invocation_id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        workflow_node_id:
          type: string
        status:
          $ref: '#/components/schemas/type_:TestRunStatus'
        agent_responses:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConversationHistoryTranscriptCommonModelOutput
        test_id:
          type: string
        test_name:
          type: string
          default: Unknown Test
        condition_result:
          $ref: '#/components/schemas/type_:TestConditionResultCommonModel'
        last_updated_at_unix:
          type: integer
        metadata:
          $ref: '#/components/schemas/type_:TestRunMetadata'
      required:
        - test_run_id
        - test_invocation_id
        - agent_id
        - status
        - test_id
    type_:GetTestSuiteInvocationResponseModel:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        created_at:
          type: integer
        test_runs:
          type: array
          items:
            $ref: '#/components/schemas/type_:UnitTestRunResponseModel'
      required:
        - id
        - test_runs

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.invocations.get("test_invocation_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.invocations.get(
    test_invocation_id="test_invocation_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Resubmit test invocation

POST https://api.elevenlabs.io/v1/convai/test-invocations/{test_invocation_id}/resubmit
Content-Type: application/json

Resubmits specific test runs from a test invocation.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/test-invocations/resubmit

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Resubmit Tests
  version: endpoint_conversationalAi/tests/invocations.resubmit
paths:
  /v1/convai/test-invocations/{test_invocation_id}/resubmit:
    post:
      operationId: resubmit
      summary: Resubmit Tests
      description: Resubmits specific test runs from a test invocation.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
          - subpackage_conversationalAi/tests/invocations
      parameters:
        - name: test_invocation_id
          in: path
          description: The id of a test invocation. This is returned when tests are run.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                test_run_ids:
                  type: array
                  items:
                    type: string
                  description: List of test run IDs to resubmit
                agent_config_override:
                  $ref: >-
                    #/components/schemas/type_:AdhocAgentConfigOverrideForTestRequestModel
                  description: >-
                    Configuration overrides to use for testing. If not provided,
                    the agent's default configuration will be used.
                agent_id:
                  type: string
                  description: Agent ID to resubmit tests for
                branch_id:
                  type: string
                  description: >-
                    ID of the branch to run the tests on. If not provided, the
                    tests will be run on the agent default configuration.
              required:
                - test_run_ids
                - agent_id
components:
  schemas:
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfig:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfig:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          default: -1
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          default: Hhmmmm...yeah.
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          default: false
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfig:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          default: 7
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          default: -1
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfig'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          default: false
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigOutput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          default: cjVigY5qzO86Huf0OWal
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          default: 0.5
          description: The stability of generated speech
        speed:
          type: number
          format: double
          default: 1
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          default: 0.8
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          default: 600
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          default: false
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetOutput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfig:
      type: object
      properties: {}
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigOutputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
      required:
        - name
        - params
    type_:BuiltInToolsOutput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigOutput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          default: 0.6
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          default: 50000
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          default: 20
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:PromptAgentApiModelOutputBackupLlmConfig:
      oneOf:
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_1
                  type: stringLiteral
                  value: default
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_2
                  type: stringLiteral
                  value: disabled
          required:
            - preference
        - type: object
          properties:
            preference:
              type: string
              enum:
                - &ref_3
                  type: stringLiteral
                  value: override
            order:
              type: array
              items:
                $ref: '#/components/schemas/type_:Llm'
          required:
            - preference
            - order
      discriminator:
        propertyName: preference
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideOutput'
    type_:ObjectOverrideOutput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideOutputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesOutput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideOutput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesOutputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyOutputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ArrayJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyOutputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyOutput'
    type_:ObjectJsonSchemaPropertyOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyOutputPropertiesValue
    type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigOutputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigOutputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigOutput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigOutputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigOutputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelOutputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesOutput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - response_timeout_secs
            - disable_interruptions
            - force_pre_tool_speech
            - assignments
            - tool_call_sound_behavior
            - dynamic_variables
            - execution_mode
            - tool_version
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyOutput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigOutputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigOutput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelOutput:
      type: object
      properties:
        prompt:
          type: string
          default: ''
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          default: 0
          description: The temperature for the LLM
        max_tokens:
          type: integer
          default: -1
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsOutput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfig'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutputBackupLlmConfig'
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          default: 8
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptAgentApiModelOutputToolsItem'
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfig:
      type: object
      properties:
        first_message:
          type: string
          default: ''
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          default: en
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          default: false
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfig'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOutput'
          description: The prompt for the agent
    type_:ConversationalConfig:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfig'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfig'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOutput'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfig'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetOutput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfig'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfig'
          description: Agent specific configuration
    type_:PromptEvaluationCriteria:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the evaluation criteria
        name:
          type: string
        type:
          type: string
          enum:
            - type: stringLiteral
              value: prompt
          description: The type of evaluation criteria
        conversation_goal_prompt:
          type: string
          description: The prompt that the agent should use to evaluate the conversation
        use_knowledge_base:
          type: boolean
          default: false
          description: >-
            When evaluating the prompt, should the agent's knowledge base be
            used.
      required:
        - id
        - name
        - conversation_goal_prompt
    type_:EvaluationSettings:
      type: object
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/type_:PromptEvaluationCriteria'
          description: Individual criteria that the agent should be evaluated against
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigOutputAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetTermsTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:WidgetLanguagePreset:
      type: object
      properties:
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
        terms_translation:
          $ref: '#/components/schemas/type_:WidgetTermsTranslation'
          description: The translation cache for the terms
    type_:WidgetConfig:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigOutputAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language_selector:
          type: boolean
          default: false
          description: Whether to show the language selector
        supports_text_only:
          type: boolean
          default: true
          description: Whether the widget can switch to text only mode
        custom_avatar_path:
          type: string
          description: The custom avatar path
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePreset'
          description: Language presets for the widget
    type_:SoftTimeoutConfigOverrideConfig:
      type: object
      properties:
        message:
          type: boolean
          default: false
          description: Whether to allow overriding the message field.
    type_:TurnConfigOverrideConfig:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:TtsConversationalConfigOverrideConfig:
      type: object
      properties:
        voice_id:
          type: boolean
          default: false
          description: Whether to allow overriding the voice_id field.
        stability:
          type: boolean
          default: false
          description: Whether to allow overriding the stability field.
        speed:
          type: boolean
          default: false
          description: Whether to allow overriding the speed field.
        similarity_boost:
          type: boolean
          default: false
          description: Whether to allow overriding the similarity_boost field.
    type_:ConversationConfigOverrideConfig:
      type: object
      properties:
        text_only:
          type: boolean
          default: false
          description: Whether to allow overriding the text_only field.
    type_:PromptAgentApiModelOverrideConfig:
      type: object
      properties:
        prompt:
          type: boolean
          default: false
          description: Whether to allow overriding the prompt field.
        llm:
          type: boolean
          default: false
          description: Whether to allow overriding the llm field.
        native_mcp_server_ids:
          type: boolean
          default: false
          description: Whether to allow overriding the native_mcp_server_ids field.
    type_:AgentConfigOverrideConfig:
      type: object
      properties:
        first_message:
          type: boolean
          default: false
          description: Whether to allow overriding the first_message field.
        language:
          type: boolean
          default: false
          description: Whether to allow overriding the language field.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationConfigClientOverrideConfigInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverrideConfig'
          description: Configures overrides for nested fields.
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverrideConfig'
          description: Configures overrides for nested fields.
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverrideConfig'
          description: Configures overrides for nested fields.
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideConfig'
          description: Configures overrides for nested fields.
    type_:ConversationInitiationClientDataConfigInput:
      type: object
      properties:
        conversation_config_override:
          $ref: >-
            #/components/schemas/type_:ConversationConfigClientOverrideConfigInput
          description: Overrides for the conversation configuration
        custom_llm_extra_body:
          type: boolean
          default: false
          description: Whether to include custom LLM extra body
        enable_conversation_initiation_client_data_from_webhook:
          type: boolean
          default: false
          description: Whether to enable conversation initiation client data from webhooks
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:AgentWorkspaceOverridesInput:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
          description: The webhook to send conversation initiation client data to
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
    type_:AttachedTestModel:
      type: object
      properties:
        test_id:
          type: string
        workflow_node_id:
          type: string
      required:
        - test_id
    type_:AgentTestingSettings:
      type: object
      properties:
        attached_tests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AttachedTestModel'
          description: List of test IDs that should be run for this agent
    type_:AuthSettings:
      type: object
      properties:
        enable_auth:
          type: boolean
          default: false
          description: >-
            If set to true, starting a conversation with an agent will require a
            signed token
        allowlist:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            A list of hosts that are allowed to start conversations with the
            agent
        require_origin_header:
          type: boolean
          default: false
          description: >-
            When enabled, connections with no origin header will be rejected. If
            the allowlist is empty, this option has no effect.
        shareable_token:
          type: string
          description: >-
            A shareable token that can be used to start a conversation with the
            agent
    type_:AgentCallLimits:
      type: object
      properties:
        agent_concurrency_limit:
          type: integer
          default: -1
          description: >-
            The maximum number of concurrent conversations. -1 indicates that
            there is no maximum
        daily_limit:
          type: integer
          default: 100000
          description: The maximum number of conversations per day
        bursting_enabled:
          type: boolean
          default: true
          description: >-
            Whether to enable bursting. If true, exceeding workspace concurrency
            limit will be allowed up to 3 times the limit. Calls will be charged
            at double rate when exceeding the limit.
    type_:PrivacyConfig:
      type: object
      properties:
        record_voice:
          type: boolean
          default: true
          description: Whether to record the conversation
        retention_days:
          type: integer
          default: -1
          description: >-
            The number of days to retain the conversation. -1 indicates there is
            no retention limit
        delete_transcript_and_pii:
          type: boolean
          default: false
          description: Whether to delete the transcript and PII
        delete_audio:
          type: boolean
          default: false
          description: Whether to delete the audio
        apply_to_existing_conversations:
          type: boolean
          default: false
          description: Whether to apply the privacy settings to existing conversations
        zero_retention_mode:
          type: boolean
          default: false
          description: Whether to enable zero retention mode - no PII data is stored
    type_:AgentPlatformSettingsRequestModel:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/type_:EvaluationSettings'
          description: Settings for evaluation
        widget:
          $ref: '#/components/schemas/type_:WidgetConfig'
          description: Configuration for the widget
        data_collection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: Data collection settings
        overrides:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataConfigInput
          description: Additional overrides for the agent during conversation initiation
        workspace_overrides:
          $ref: '#/components/schemas/type_:AgentWorkspaceOverridesInput'
          description: Workspace overrides for the agent
        testing:
          $ref: '#/components/schemas/type_:AgentTestingSettings'
          description: Testing configuration for the agent
        archived:
          type: boolean
          default: false
          description: Whether the agent is archived
        auth:
          $ref: '#/components/schemas/type_:AuthSettings'
          description: Settings for authentication
        call_limits:
          $ref: '#/components/schemas/type_:AgentCallLimits'
          description: Call limits for the agent
        privacy:
          $ref: '#/components/schemas/type_:PrivacyConfig'
          description: Privacy settings for the agent
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_4
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_1
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_2
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - *ref_3
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_4
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:AdhocAgentConfigOverrideForTestRequestModel:
      type: object
      properties:
        conversation_config:
          $ref: '#/components/schemas/type_:ConversationalConfig'
        platform_settings:
          $ref: '#/components/schemas/type_:AgentPlatformSettingsRequestModel'
        workflow:
          $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
      required:
        - conversation_config
        - platform_settings

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.invocations.resubmit("test_invocation_id", {
        testRunIds: [
            "test_run_ids",
        ],
        agentId: "agent_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.invocations.resubmit(
    test_invocation_id="test_invocation_id",
    test_run_ids=[
        "test_run_ids"
    ],
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit"

	payload := strings.NewReader("{\n  \"test_run_ids\": [\n    \"test_run_ids\"\n  ],\n  \"agent_id\": \"agent_id\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"test_run_ids\": [\n    \"test_run_ids\"\n  ],\n  \"agent_id\": \"agent_id\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit")
  .header("Content-Type", "application/json")
  .body("{\n  \"test_run_ids\": [\n    \"test_run_ids\"\n  ],\n  \"agent_id\": \"agent_id\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit', [
  'body' => '{
  "test_run_ids": [
    "test_run_ids"
  ],
  "agent_id": "agent_id"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"test_run_ids\": [\n    \"test_run_ids\"\n  ],\n  \"agent_id\": \"agent_id\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "test_run_ids": ["test_run_ids"],
  "agent_id": "agent_id"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/test-invocations/test_invocation_id/resubmit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List test invocations

GET https://api.elevenlabs.io/v1/convai/test-invocations

Lists all test invocations with pagination support and optional search filtering.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/tests/test-invocations/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Test Invocations
  version: endpoint_conversationalAi/tests/invocations.list
paths:
  /v1/convai/test-invocations:
    get:
      operationId: list
      summary: List Test Invocations
      description: >-
        Lists all test invocations with pagination support and optional search
        filtering.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/tests
          - subpackage_conversationalAi/tests/invocations
      parameters:
        - name: agent_id
          in: query
          description: Filter by agent ID
          required: true
          schema:
            type: string
        - name: page_size
          in: query
          description: >-
            How many Tests to return at maximum. Can not exceed 100, defaults to
            30.
          required: false
          schema:
            type: integer
            default: 30
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetTestInvocationsPageResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ListResponseMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:TestInvocationSummaryResponseModel:
      type: object
      properties:
        id:
          type: string
          description: The ID of the test invocation
        agent_id:
          type: string
          description: The ID of the agent this test invocation belongs to
        branch_id:
          type: string
          description: The ID of the branch this test invocation was run on
        created_at_unix_secs:
          type: integer
          description: Creation time of the test invocation in unix seconds
        test_run_count:
          type: integer
          description: Number of test runs in this invocation
        passed_count:
          type: integer
          description: Number of test runs that passed
        failed_count:
          type: integer
          description: Number of test runs that failed
        pending_count:
          type: integer
          description: Number of test runs that are pending
        title:
          type: string
          description: >-
            Title of the test invocation - either the single test name or count
            of tests
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the test invocation
      required:
        - id
        - created_at_unix_secs
        - test_run_count
        - passed_count
        - failed_count
        - pending_count
        - title
    type_:GetTestInvocationsPageResponseModel:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/type_:ListResponseMeta'
        results:
          type: array
          items:
            $ref: '#/components/schemas/type_:TestInvocationSummaryResponseModel'
        next_cursor:
          type: string
          description: Cursor for the next page of results
        has_more:
          type: boolean
          description: Whether there are more results available
      required:
        - results
        - has_more

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.tests.invocations.list({
        agentId: "agent_id",
        pageSize: 1,
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.tests.invocations.list(
    agent_id="agent_id",
    page_size=1,
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/test-invocations?agent_id=agent_id&page_size=1&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Import phone number

POST https://api.elevenlabs.io/v1/convai/phone-numbers
Content-Type: application/json

Import Phone Number from provider configuration (Twilio or SIP trunk)

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/phone-numbers/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Import Phone Number
  version: endpoint_conversationalAi/phoneNumbers.create
paths:
  /v1/convai/phone-numbers:
    post:
      operationId: create
      summary: Import Phone Number
      description: Import Phone Number from provider configuration (Twilio or SIP trunk)
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/phoneNumbers
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreatePhoneNumberResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        description: Create Phone Request Information
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/type_conversationalAi/phoneNumbers:PhoneNumbersCreateRequestBody
components:
  schemas:
    type_:TwilioRegionId:
      type: string
      enum:
        - value: us1
        - value: ie1
        - value: au1
    type_:TwilioEdgeLocation:
      type: string
      enum:
        - value: ashburn
        - value: dublin
        - value: frankfurt
        - value: sao-paulo
        - value: singapore
        - value: sydney
        - value: tokyo
        - value: umatilla
        - value: roaming
    type_:RegionConfigRequest:
      type: object
      properties:
        region_id:
          $ref: '#/components/schemas/type_:TwilioRegionId'
          description: Region ID
        token:
          type: string
          description: Auth Token for this region
        edge_location:
          $ref: '#/components/schemas/type_:TwilioEdgeLocation'
          description: Edge location for this region
      required:
        - region_id
        - token
        - edge_location
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:SipTrunkCredentialsRequestModel:
      type: object
      properties:
        username:
          type: string
          description: SIP trunk username
        password:
          type: string
          description: SIP trunk password - if not specified, then remain unchanged
      required:
        - username
    type_:InboundSipTrunkConfigRequestModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        credentials:
          $ref: '#/components/schemas/type_:SipTrunkCredentialsRequestModel'
          description: Optional digest authentication credentials (username/password).
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:OutboundSipTrunkConfigRequestModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to.
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport (signalling layer).
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: >-
            SIP X-* headers for INVITE request. These headers are sent as-is and
            may help identify this call.
        credentials:
          $ref: '#/components/schemas/type_:SipTrunkCredentialsRequestModel'
          description: >-
            Optional digest authentication credentials (username/password). If
            not provided, ACL authentication is assumed.
      required:
        - address
    type_conversationalAi/phoneNumbers:PhoneNumbersCreateRequestBody:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            sid:
              type: string
              description: Twilio Account SID
            token:
              type: string
              description: Twilio Auth Token
            region_config:
              $ref: '#/components/schemas/type_:RegionConfigRequest'
              description: Twilio Additional Region Configuration
          required:
            - provider
            - phone_number
            - label
            - sid
            - token
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            inbound_trunk_config:
              $ref: '#/components/schemas/type_:InboundSipTrunkConfigRequestModel'
            outbound_trunk_config:
              $ref: '#/components/schemas/type_:OutboundSipTrunkConfigRequestModel'
          required:
            - provider
            - phone_number
            - label
      discriminator:
        propertyName: provider
    type_:CreatePhoneNumberResponseModel:
      type: object
      properties:
        phone_number_id:
          type: string
          description: Phone entity ID
      required:
        - phone_number_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.phoneNumbers.create({
        provider: "twilio",
        label: "label",
        phoneNumber: "phone_number",
        sid: "sid",
        token: "token",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.phone_numbers.create(
    request={
        "provider": "twilio",
        "label": "label",
        "phone_number": "phone_number",
        "sid": "sid",
        "token": "token"
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/phone-numbers"

	payload := strings.NewReader("{\n  \"provider\": \"twilio\",\n  \"label\": \"label\",\n  \"phone_number\": \"phone_number\",\n  \"sid\": \"sid\",\n  \"token\": \"token\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/phone-numbers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"twilio\",\n  \"label\": \"label\",\n  \"phone_number\": \"phone_number\",\n  \"sid\": \"sid\",\n  \"token\": \"token\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/phone-numbers")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"twilio\",\n  \"label\": \"label\",\n  \"phone_number\": \"phone_number\",\n  \"sid\": \"sid\",\n  \"token\": \"token\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/phone-numbers', [
  'body' => '{
  "provider": "twilio",
  "label": "label",
  "phone_number": "phone_number",
  "sid": "sid",
  "token": "token"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/phone-numbers");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"provider\": \"twilio\",\n  \"label\": \"label\",\n  \"phone_number\": \"phone_number\",\n  \"sid\": \"sid\",\n  \"token\": \"token\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "provider": "twilio",
  "label": "label",
  "phone_number": "phone_number",
  "sid": "sid",
  "token": "token"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/phone-numbers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List phone numbers

GET https://api.elevenlabs.io/v1/convai/phone-numbers

Retrieve all Phone Numbers

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/phone-numbers/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Phone Numbers
  version: endpoint_conversationalAi/phoneNumbers.list
paths:
  /v1/convai/phone-numbers:
    get:
      operationId: list
      summary: List Phone Numbers
      description: Retrieve all Phone Numbers
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/phoneNumbers
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: >-
                    #/components/schemas/type_conversationalAi/phoneNumbers:PhoneNumbersListResponseItem
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:PhoneNumberAgentInfo:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        agent_name:
          type: string
          description: The name of the agent
      required:
        - agent_id
        - agent_name
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: SIP headers for INVITE request
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        has_outbound_trunk:
          type: boolean
          default: false
          description: Whether a LiveKit SIP outbound trunk is configured
      required:
        - address
        - transport
        - media_encryption
        - has_auth_credentials
    type_:GetPhoneNumberInboundSipTrunkConfigResponseModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
      required:
        - allowed_addresses
        - media_encryption
        - has_auth_credentials
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_conversationalAi/phoneNumbers:PhoneNumbersListResponseItem:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
            provider_config:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
            outbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
              description: Configuration of the Outbound SIP trunk - if configured.
            inbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberInboundSipTrunkConfigResponseModel
              description: Configuration of the Inbound SIP trunk - if configured.
            livekit_stack:
              $ref: '#/components/schemas/type_:LivekitStackType'
              description: Type of Livekit stack used for this number.
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
            - livekit_stack
      discriminator:
        propertyName: provider

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.phoneNumbers.list();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.phone_numbers.list()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/phone-numbers"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/phone-numbers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/phone-numbers")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/phone-numbers');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/phone-numbers");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/phone-numbers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get phone number

GET https://api.elevenlabs.io/v1/convai/phone-numbers/{phone_number_id}

Retrieve Phone Number details by ID

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/phone-numbers/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Phone Number
  version: endpoint_conversationalAi/phoneNumbers.get
paths:
  /v1/convai/phone-numbers/{phone_number_id}:
    get:
      operationId: get
      summary: Get Phone Number
      description: Retrieve Phone Number details by ID
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/phoneNumbers
      parameters:
        - name: phone_number_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_conversationalAi/phoneNumbers:PhoneNumbersGetResponse
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:PhoneNumberAgentInfo:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        agent_name:
          type: string
          description: The name of the agent
      required:
        - agent_id
        - agent_name
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: SIP headers for INVITE request
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        has_outbound_trunk:
          type: boolean
          default: false
          description: Whether a LiveKit SIP outbound trunk is configured
      required:
        - address
        - transport
        - media_encryption
        - has_auth_credentials
    type_:GetPhoneNumberInboundSipTrunkConfigResponseModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
      required:
        - allowed_addresses
        - media_encryption
        - has_auth_credentials
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_conversationalAi/phoneNumbers:PhoneNumbersGetResponse:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
            provider_config:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
            outbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
              description: Configuration of the Outbound SIP trunk - if configured.
            inbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberInboundSipTrunkConfigResponseModel
              description: Configuration of the Inbound SIP trunk - if configured.
            livekit_stack:
              $ref: '#/components/schemas/type_:LivekitStackType'
              description: Type of Livekit stack used for this number.
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
            - livekit_stack
      discriminator:
        propertyName: provider

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.phoneNumbers.get("TeaqRRdTcIfIu2i7BYfT");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.phone_numbers.get(
    phone_number_id="TeaqRRdTcIfIu2i7BYfT"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update phone number

PATCH https://api.elevenlabs.io/v1/convai/phone-numbers/{phone_number_id}
Content-Type: application/json

Update assigned agent of a phone number

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/phone-numbers/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Phone Number
  version: endpoint_conversationalAi/phoneNumbers.update
paths:
  /v1/convai/phone-numbers/{phone_number_id}:
    patch:
      operationId: update
      summary: Update Phone Number
      description: Update assigned agent of a phone number
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/phoneNumbers
      parameters:
        - name: phone_number_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_conversationalAi/phoneNumbers:PhoneNumbersUpdateResponse
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                label:
                  type: string
                inbound_trunk_config:
                  $ref: '#/components/schemas/type_:InboundSipTrunkConfigRequestModel'
                outbound_trunk_config:
                  $ref: >-
                    #/components/schemas/type_:OutboundSipTrunkConfigRequestModel
                livekit_stack:
                  $ref: '#/components/schemas/type_:LivekitStackType'
components:
  schemas:
    type_:SipMediaEncryptionEnum:
      type: string
      enum:
        - value: disabled
        - value: allowed
        - value: required
    type_:SipTrunkCredentialsRequestModel:
      type: object
      properties:
        username:
          type: string
          description: SIP trunk username
        password:
          type: string
          description: SIP trunk password - if not specified, then remain unchanged
      required:
        - username
    type_:InboundSipTrunkConfigRequestModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        credentials:
          $ref: '#/components/schemas/type_:SipTrunkCredentialsRequestModel'
          description: Optional digest authentication credentials (username/password).
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
    type_:SipTrunkTransportEnum:
      type: string
      enum:
        - value: auto
        - value: udp
        - value: tcp
        - value: tls
    type_:OutboundSipTrunkConfigRequestModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to.
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport (signalling layer).
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: >-
            SIP X-* headers for INVITE request. These headers are sent as-is and
            may help identify this call.
        credentials:
          $ref: '#/components/schemas/type_:SipTrunkCredentialsRequestModel'
          description: >-
            Optional digest authentication credentials (username/password). If
            not provided, ACL authentication is assumed.
      required:
        - address
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_:PhoneNumberAgentInfo:
      type: object
      properties:
        agent_id:
          type: string
          description: The ID of the agent
        agent_name:
          type: string
          description: The name of the agent
      required:
        - agent_id
        - agent_name
    type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel:
      type: object
      properties:
        address:
          type: string
          description: Hostname or IP the SIP INVITE is sent to
        transport:
          $ref: '#/components/schemas/type_:SipTrunkTransportEnum'
          description: Protocol to use for SIP transport
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
        headers:
          type: object
          additionalProperties:
            type: string
          description: SIP headers for INVITE request
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        has_outbound_trunk:
          type: boolean
          default: false
          description: Whether a LiveKit SIP outbound trunk is configured
      required:
        - address
        - transport
        - media_encryption
        - has_auth_credentials
    type_:GetPhoneNumberInboundSipTrunkConfigResponseModel:
      type: object
      properties:
        allowed_addresses:
          type: array
          items:
            type: string
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          type: array
          items:
            type: string
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/type_:SipMediaEncryptionEnum'
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
        username:
          type: string
          description: SIP trunk username (if available)
        remote_domains:
          type: array
          items:
            type: string
          description: Domains of remote SIP servers used to validate TLS certificates.
      required:
        - allowed_addresses
        - media_encryption
        - has_auth_credentials
    type_conversationalAi/phoneNumbers:PhoneNumbersUpdateResponse:
      oneOf:
        - type: object
          properties:
            provider:
              type: string
              enum:
                - twilio
              description: 'Discriminator value: twilio'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
        - type: object
          properties:
            provider:
              type: string
              enum:
                - sip_trunk
              description: 'Discriminator value: sip_trunk'
            phone_number:
              type: string
              description: Phone number
            label:
              type: string
              description: Label for the phone number
            supports_inbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports inbound calls
            supports_outbound:
              type: boolean
              default: true
              description: >-
                This field is deprecated and will be removed in the future.
                Whether this phone number supports outbound calls
            phone_number_id:
              type: string
              description: The ID of the phone number
            assigned_agent:
              $ref: '#/components/schemas/type_:PhoneNumberAgentInfo'
              description: The agent that is assigned to the phone number
            provider_config:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
            outbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberOutboundSipTrunkConfigResponseModel
              description: Configuration of the Outbound SIP trunk - if configured.
            inbound_trunk:
              $ref: >-
                #/components/schemas/type_:GetPhoneNumberInboundSipTrunkConfigResponseModel
              description: Configuration of the Inbound SIP trunk - if configured.
            livekit_stack:
              $ref: '#/components/schemas/type_:LivekitStackType'
              description: Type of Livekit stack used for this number.
          required:
            - provider
            - phone_number
            - label
            - phone_number_id
            - livekit_stack
      discriminator:
        propertyName: provider

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.phoneNumbers.update("TeaqRRdTcIfIu2i7BYfT", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.phone_numbers.update(
    phone_number_id="TeaqRRdTcIfIu2i7BYfT"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete phone number

DELETE https://api.elevenlabs.io/v1/convai/phone-numbers/{phone_number_id}

Delete Phone Number by ID

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/phone-numbers/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Phone Number
  version: endpoint_conversationalAi/phoneNumbers.delete
paths:
  /v1/convai/phone-numbers/{phone_number_id}:
    delete:
      operationId: delete
      summary: Delete Phone Number
      description: Delete Phone Number by ID
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/phoneNumbers
      parameters:
        - name: phone_number_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.phoneNumbers.delete("TeaqRRdTcIfIu2i7BYfT");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.phone_numbers.delete(
    phone_number_id="TeaqRRdTcIfIu2i7BYfT"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/phone-numbers/TeaqRRdTcIfIu2i7BYfT")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get widget

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/widget

Retrieve the widget configuration for an agent

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/widget/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Widget Config
  version: endpoint_conversationalAi/agents/widget.get
paths:
  /v1/convai/agents/{agent_id}/widget:
    get:
      operationId: get
      summary: Get Agent Widget Config
      description: Retrieve the widget configuration for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/widget
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: conversation_signature
          in: query
          description: >-
            An expiring token that enables a websocket conversation to start.
            These can be generated for an agent using the
            /v1/convai/conversation/get-signed-url endpoint
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetAgentEmbedResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:EmbedVariant:
      type: string
      enum:
        - value: tiny
        - value: compact
        - value: full
        - value: expandable
    type_:WidgetPlacement:
      type: string
      enum:
        - value: top-left
        - value: top
        - value: top-right
        - value: bottom-left
        - value: bottom
        - value: bottom-right
    type_:WidgetExpandable:
      type: string
      enum:
        - value: never
        - value: mobile
        - value: desktop
        - value: always
    type_:WidgetConfigResponseModelAvatar:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - orb
              description: 'Discriminator value: orb'
            color_1:
              type: string
              default: '#2792dc'
              description: The first color of the avatar
            color_2:
              type: string
              default: '#9ce6e6'
              description: The second color of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - url
              description: 'Discriminator value: url'
            custom_url:
              type: string
              default: ''
              description: The custom URL of the avatar
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            url:
              type: string
              default: ''
              description: The URL of the avatar
          required:
            - type
      discriminator:
        propertyName: type
    type_:WidgetFeedbackMode:
      type: string
      enum:
        - value: none
        - value: during
        - value: end
    type_:WidgetEndFeedbackType:
      type: string
      enum:
        - type: stringLiteral
          value: rating
    type_:WidgetEndFeedbackConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
    type_:AllowlistItem:
      type: object
      properties:
        hostname:
          type: string
          description: The hostname of the allowed origin
      required:
        - hostname
    type_:WidgetTextContents:
      type: object
      properties:
        main_label:
          type: string
          description: Call to action displayed inside the compact and full variants.
        start_call:
          type: string
          description: Text and ARIA label for the start call button.
        start_chat:
          type: string
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          type: string
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call in order ot start the next
            one.
        end_call:
          type: string
          description: Text and ARIA label for the end call button.
        mute_microphone:
          type: string
          description: ARIA label for the mute microphone button.
        change_language:
          type: string
          description: ARIA label for the change language dropdown.
        collapse:
          type: string
          description: ARIA label for the collapse button.
        expand:
          type: string
          description: ARIA label for the expand button.
        copied:
          type: string
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          type: string
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          type: string
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          type: string
          description: Status displayed when the agent is listening.
        speaking_status:
          type: string
          description: Status displayed when the agent is speaking.
        connecting_status:
          type: string
          description: Status displayed when the agent is connecting.
        chatting_status:
          type: string
          description: Status displayed when the agent is chatting (text only)
        input_label:
          type: string
          description: ARIA label for the text message input.
        input_placeholder:
          type: string
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          type: string
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          type: string
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          type: string
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          type: string
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          type: string
          description: Text label used next to the conversation ID.
        error_occurred:
          type: string
          description: Text label used when an error occurs.
        copy_id:
          type: string
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          type: string
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          type: string
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          type: string
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          type: string
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          type: string
          description: Placeholder text for the follow-up feedback input field.
        submit:
          type: string
          description: Text and ARIA label for the submit button.
        go_back:
          type: string
          description: Text and ARIA label for the go back button.
    type_:WidgetStyles:
      type: object
      properties:
        base:
          type: string
          description: The base background color.
        base_hover:
          type: string
          description: The color of the base background when hovered.
        base_active:
          type: string
          description: The color of the base background when active (clicked).
        base_border:
          type: string
          description: The color of the border against the base background.
        base_subtle:
          type: string
          description: The color of subtle text against the base background.
        base_primary:
          type: string
          description: The color of primary text against the base background.
        base_error:
          type: string
          description: The color of error text against the base background.
        accent:
          type: string
          description: The accent background color.
        accent_hover:
          type: string
          description: The color of the accent background when hovered.
        accent_active:
          type: string
          description: The color of the accent background when active (clicked).
        accent_border:
          type: string
          description: The color of the border against the accent background.
        accent_subtle:
          type: string
          description: The color of subtle text against the accent background.
        accent_primary:
          type: string
          description: The color of primary text against the accent background.
        overlay_padding:
          type: number
          format: double
          description: The padding around the edges of the viewport.
        button_radius:
          type: number
          format: double
          description: The radius of the buttons.
        input_radius:
          type: number
          format: double
          description: The radius of the input fields.
        bubble_radius:
          type: number
          format: double
          description: The radius of the chat bubbles.
        sheet_radius:
          type: number
          format: double
          description: The default radius of sheets.
        compact_sheet_radius:
          type: number
          format: double
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          type: number
          format: double
          description: The radius of the dropdown sheet.
    type_:WidgetLanguagePresetResponse:
      type: object
      properties:
        first_message:
          type: string
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: The text contents for the selected language
        terms_text:
          type: string
          description: The text to display for terms and conditions in this language
        terms_html:
          type: string
          description: The HTML to display for terms and conditions in this language
        terms_key:
          type: string
          description: The key to display for terms and conditions in this language
    type_:WidgetConfigResponse:
      type: object
      properties:
        variant:
          $ref: '#/components/schemas/type_:EmbedVariant'
          description: The variant of the widget
        placement:
          $ref: '#/components/schemas/type_:WidgetPlacement'
          description: The placement of the widget on the screen
        expandable:
          $ref: '#/components/schemas/type_:WidgetExpandable'
          description: Whether the widget is expandable
        avatar:
          $ref: '#/components/schemas/type_:WidgetConfigResponseModelAvatar'
          description: The avatar of the widget
        feedback_mode:
          $ref: '#/components/schemas/type_:WidgetFeedbackMode'
          description: The feedback mode of the widget
        end_feedback:
          $ref: '#/components/schemas/type_:WidgetEndFeedbackConfig'
          description: Configuration for feedback collected at the end of the conversation
        bg_color:
          type: string
          default: '#ffffff'
          description: The background color of the widget
        text_color:
          type: string
          default: '#000000'
          description: The text color of the widget
        btn_color:
          type: string
          default: '#000000'
          description: The button color of the widget
        btn_text_color:
          type: string
          default: '#ffffff'
          description: The button text color of the widget
        border_color:
          type: string
          default: '#e1e1e1'
          description: The border color of the widget
        focus_color:
          type: string
          default: '#000000'
          description: The focus color of the widget
        border_radius:
          type: integer
          description: The border radius of the widget
        btn_radius:
          type: integer
          description: The button radius of the widget
        action_text:
          type: string
          description: The action text of the widget
        start_call_text:
          type: string
          description: The start call text of the widget
        end_call_text:
          type: string
          description: The end call text of the widget
        expand_text:
          type: string
          description: The expand text of the widget
        listening_text:
          type: string
          description: The text to display when the agent is listening
        speaking_text:
          type: string
          description: The text to display when the agent is speaking
        shareable_page_text:
          type: string
          description: The text to display when sharing
        shareable_page_show_terms:
          type: boolean
          default: true
          description: Whether to show terms and conditions on the shareable page
        terms_text:
          type: string
          description: The text to display for terms and conditions
        terms_html:
          type: string
          description: The HTML to display for terms and conditions
        terms_key:
          type: string
          description: The key to display for terms and conditions
        show_avatar_when_collapsed:
          type: boolean
          description: Whether to show the avatar when the widget is collapsed
        disable_banner:
          type: boolean
          default: false
          description: Whether to disable the banner
        override_link:
          type: string
          description: The override link for the widget
        markdown_link_allowed_hosts:
          type: array
          items:
            $ref: '#/components/schemas/type_:AllowlistItem'
          description: >-
            List of allowed hostnames for clickable markdown links. Use {
            hostname: '*' } to allow any domain. Empty means no links are
            allowed.
        markdown_link_include_www:
          type: boolean
          default: true
          description: Whether to automatically include www. variants of allowed hosts
        markdown_link_allow_http:
          type: boolean
          default: true
          description: Whether to allow http:// in addition to https:// for allowed hosts
        mic_muting_enabled:
          type: boolean
          default: false
          description: Whether to enable mic muting
        transcript_enabled:
          type: boolean
          default: false
          description: >-
            Whether the widget should show the conversation transcript as it
            goes on
        text_input_enabled:
          type: boolean
          default: true
          description: Whether the user should be able to send text messages
        conversation_mode_toggle_enabled:
          type: boolean
          default: false
          description: Whether to enable the conversation mode toggle in the widget
        default_expanded:
          type: boolean
          default: false
          description: Whether the widget should be expanded by default
        always_expanded:
          type: boolean
          default: false
          description: Whether the widget should always be expanded
        text_contents:
          $ref: '#/components/schemas/type_:WidgetTextContents'
          description: Text contents of the widget
        styles:
          $ref: '#/components/schemas/type_:WidgetStyles'
          description: Styles for the widget
        language:
          type: string
        supported_language_overrides:
          type: array
          items:
            type: string
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WidgetLanguagePresetResponse'
          description: Language presets for the widget
        text_only:
          type: boolean
          default: false
          description: Whether the agent uses text-only mode
        supports_text_only:
          type: boolean
          default: false
          description: Whether the agent can be switched to text-only mode
        first_message:
          type: string
        use_rtc:
          type: boolean
          description: Whether to use WebRTC for conversation connections
      required:
        - language
    type_:GetAgentEmbedResponseModel:
      type: object
      properties:
        agent_id:
          type: string
        widget_config:
          $ref: '#/components/schemas/type_:WidgetConfigResponse'
      required:
        - agent_id
        - widget_config

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.widget.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        conversationSignature: "conversation_signature",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.widget.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    conversation_signature="conversation_signature"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget?conversation_signature=conversation_signature")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create widget avatar

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/avatar
Content-Type: multipart/form-data

Sets the avatar for an agent displayed in the widget

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/widget/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Post Agent Avatar
  version: endpoint_conversationalAi/agents/widget/avatar.create
paths:
  /v1/convai/agents/{agent_id}/avatar:
    post:
      operationId: create
      summary: Post Agent Avatar
      description: Sets the avatar for an agent displayed in the widget
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/widget
          - subpackage_conversationalAi/agents/widget/avatar
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:PostAgentAvatarResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar_file:
                  type: string
                  format: binary
                  description: An image file to be used as the agent's avatar.
              required:
                - avatar_file
components:
  schemas:
    type_:PostAgentAvatarResponseModel:
      type: object
      properties:
        agent_id:
          type: string
        avatar_url:
          type: string
      required:
        - agent_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.widget.avatar.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.widget.avatar.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"avatar_file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"avatar_file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"avatar_file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar', [
  'multipart' => [
    [
        'name' => 'avatar_file',
        'filename' => '<file1>',
        'contents' => null
    ]
  ]
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar");
var request = new RestRequest(Method.POST);
request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"avatar_file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "multipart/form-data; boundary=---011000010111000001101001"]
let parameters = [
  [
    "name": "avatar_file",
    "fileName": "<file1>"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/avatar")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get settings

GET https://api.elevenlabs.io/v1/convai/settings

Retrieve Convai settings for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Convai Settings
  version: endpoint_conversationalAi/settings.get
paths:
  /v1/convai/settings:
    get:
      operationId: get
      summary: Get Convai Settings
      description: Retrieve Convai settings for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/settings
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetConvAiSettingsResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_:GetConvAiSettingsResponseModel:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
        can_use_mcp_servers:
          type: boolean
          default: false
          description: Whether the workspace can use MCP servers
        rag_retention_period_days:
          type: integer
          default: 10
        default_livekit_stack:
          $ref: '#/components/schemas/type_:LivekitStackType'

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.settings.get();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.settings.get()

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/settings"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/settings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/settings")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/settings', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/settings");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/settings")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update settings

PATCH https://api.elevenlabs.io/v1/convai/settings
Content-Type: application/json

Update Convai settings for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Convai Settings
  version: endpoint_conversationalAi/settings.update
paths:
  /v1/convai/settings:
    patch:
      operationId: update
      summary: Update Convai Settings
      description: Update Convai settings for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/settings
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetConvAiSettingsResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_initiation_client_data_webhook:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataWebhook
                webhooks:
                  $ref: '#/components/schemas/type_:ConvAiWebhooks'
                can_use_mcp_servers:
                  type: boolean
                  default: false
                  description: Whether the workspace can use MCP servers
                rag_retention_period_days:
                  type: integer
                  default: 10
                default_livekit_stack:
                  $ref: '#/components/schemas/type_:LivekitStackType'
components:
  schemas:
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConversationInitiationClientDataWebhookRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConversationInitiationClientDataWebhook:
      type: object
      properties:
        url:
          type: string
          description: The URL to send the webhook to
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataWebhookRequestHeadersValue
          description: The headers to send with the webhook request
      required:
        - url
        - request_headers
    type_:WebhookEventType:
      type: string
      enum:
        - value: transcript
        - value: audio
        - value: call_initiation_failure
    type_:ConvAiWebhooks:
      type: object
      properties:
        post_call_webhook_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/type_:WebhookEventType'
          description: >-
            List of event types to send via webhook. Options: transcript, audio,
            call_initiation_failure.
        send_audio:
          type: boolean
          description: >-
            DEPRECATED: Use 'events' field instead. Whether to send audio data
            with post-call webhooks for ConvAI conversations
    type_:LivekitStackType:
      type: string
      enum:
        - value: standard
        - value: static
    type_:GetConvAiSettingsResponseModel:
      type: object
      properties:
        conversation_initiation_client_data_webhook:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataWebhook'
        webhooks:
          $ref: '#/components/schemas/type_:ConvAiWebhooks'
        can_use_mcp_servers:
          type: boolean
          default: false
          description: Whether the workspace can use MCP servers
        rag_retention_period_days:
          type: integer
          default: 10
        default_livekit_stack:
          $ref: '#/components/schemas/type_:LivekitStackType'

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.settings.update({});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.settings.update()

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/settings"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/settings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/settings")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/settings', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/settings");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/settings")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get secrets

GET https://api.elevenlabs.io/v1/convai/secrets

Get all workspace secrets for the user

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/secrets/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Convai Workspace Secrets
  version: endpoint_conversationalAi/secrets.list
paths:
  /v1/convai/secrets:
    get:
      operationId: list
      summary: Get Convai Workspace Secrets
      description: Get all workspace secrets for the user
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/secrets
      parameters:
        - name: page_size
          in: query
          description: >-
            How many documents to return at maximum. Can not exceed 100. If not
            provided, returns all secrets.
          required: false
          schema:
            type: integer
        - name: cursor
          in: query
          description: Used for fetching next page. Cursor is returned in the response.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetWorkspaceSecretsResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:DependentAvailableToolIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ConvAiStoredSecretDependenciesToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableToolIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
          required:
            - type
      discriminator:
        propertyName: type
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ConvAiStoredSecretDependenciesAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:SecretDependencyType:
      type: string
      enum:
        - type: stringLiteral
          value: conversation_initiation_webhook
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:DependentPhoneNumberIdentifier:
      type: object
      properties:
        phone_number_id:
          type: string
        phone_number:
          type: string
        label:
          type: string
        provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
      required:
        - phone_number_id
        - phone_number
        - label
        - provider
    type_:ConvAiStoredSecretDependencies:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:ConvAiStoredSecretDependenciesToolsItem'
        agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:ConvAiStoredSecretDependenciesAgentsItem
        others:
          type: array
          items:
            $ref: '#/components/schemas/type_:SecretDependencyType'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/type_:DependentPhoneNumberIdentifier'
      required:
        - tools
        - agents
        - others
    type_:ConvAiWorkspaceStoredSecretConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: stored
        secret_id:
          type: string
        name:
          type: string
        used_by:
          $ref: '#/components/schemas/type_:ConvAiStoredSecretDependencies'
      required:
        - type
        - secret_id
        - name
        - used_by
    type_:GetWorkspaceSecretsResponseModel:
      type: object
      properties:
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/type_:ConvAiWorkspaceStoredSecretConfig'
        next_cursor:
          type: string
          description: Cursor for fetching the next page of secrets
        has_more:
          type: boolean
          default: false
          description: Whether there are more secrets to fetch
      required:
        - secrets

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.secrets.list({
        pageSize: 1,
        cursor: "cursor",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.secrets.list(
    page_size=1,
    cursor="cursor"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/secrets?page_size=1&cursor=cursor")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create secret

POST https://api.elevenlabs.io/v1/convai/secrets
Content-Type: application/json

Create a new secret for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/secrets/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Convai Workspace Secret
  version: endpoint_conversationalAi/secrets.create
paths:
  /v1/convai/secrets:
    post:
      operationId: create
      summary: Create Convai Workspace Secret
      description: Create a new secret for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/secrets
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:PostWorkspaceSecretResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - type: stringLiteral
                      value: new
                name:
                  type: string
                value:
                  type: string
              required:
                - type
                - name
                - value
components:
  schemas:
    type_:PostWorkspaceSecretResponseModel:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: stored
        secret_id:
          type: string
        name:
          type: string
      required:
        - type
        - secret_id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.secrets.create({
        type: "new",
        name: "name",
        value: "value",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.secrets.create(
    type="new",
    name="name",
    value="value"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/secrets"

	payload := strings.NewReader("{\n  \"type\": \"new\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/secrets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"new\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/secrets")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"new\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/secrets', [
  'body' => '{
  "type": "new",
  "name": "name",
  "value": "value"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/secrets");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"type\": \"new\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "type": "new",
  "name": "name",
  "value": "value"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/secrets")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update secret

PATCH https://api.elevenlabs.io/v1/convai/secrets/{secret_id}
Content-Type: application/json

Update an existing secret for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/secrets/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Convai Workspace Secret
  version: endpoint_conversationalAi/secrets.update
paths:
  /v1/convai/secrets/{secret_id}:
    patch:
      operationId: update
      summary: Update Convai Workspace Secret
      description: Update an existing secret for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/secrets
      parameters:
        - name: secret_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:PostWorkspaceSecretResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - type: stringLiteral
                      value: update
                name:
                  type: string
                value:
                  type: string
              required:
                - type
                - name
                - value
components:
  schemas:
    type_:PostWorkspaceSecretResponseModel:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: stored
        secret_id:
          type: string
        name:
          type: string
      required:
        - type
        - secret_id
        - name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.secrets.update("secret_id", {
        type: "update",
        name: "name",
        value: "value",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.secrets.update(
    secret_id="secret_id",
    type="update",
    name="name",
    value="value"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/secrets/secret_id"

	payload := strings.NewReader("{\n  \"type\": \"update\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/secrets/secret_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"update\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/secrets/secret_id")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"update\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/secrets/secret_id', [
  'body' => '{
  "type": "update",
  "name": "name",
  "value": "value"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/secrets/secret_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"type\": \"update\",\n  \"name\": \"name\",\n  \"value\": \"value\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "type": "update",
  "name": "name",
  "value": "value"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/secrets/secret_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete secret

DELETE https://api.elevenlabs.io/v1/convai/secrets/{secret_id}

Delete a workspace secret if it's not in use

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/secrets/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Convai Workspace Secret
  version: endpoint_conversationalAi/secrets.delete
paths:
  /v1/convai/secrets/{secret_id}:
    delete:
      operationId: delete
      summary: Delete Convai Workspace Secret
      description: Delete a workspace secret if it's not in use
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/secrets
      parameters:
        - name: secret_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.secrets.delete("secret_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.secrets.delete(
    secret_id="secret_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/secrets/secret_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/secrets/secret_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/secrets/secret_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/secrets/secret_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/secrets/secret_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/secrets/secret_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get dashboard settings

GET https://api.elevenlabs.io/v1/convai/settings/dashboard

Retrieve Convai dashboard settings for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/dashboard/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Convai Dashboard Settings
  version: endpoint_conversationalAi/dashboard/settings.get
paths:
  /v1/convai/settings/dashboard:
    get:
      operationId: get
      summary: Get Convai Dashboard Settings
      description: Retrieve Convai dashboard settings for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/dashboard
          - subpackage_conversationalAi/dashboard/settings
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:GetConvAiDashboardSettingsResponseModel
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetConvAiDashboardSettingsResponseModelChartsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - call_success
              description: 'Discriminator value: call_success'
            name:
              type: string
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - criteria
              description: 'Discriminator value: criteria'
            name:
              type: string
            criteria_id:
              type: string
          required:
            - type
            - name
            - criteria_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - data_collection
              description: 'Discriminator value: data_collection'
            name:
              type: string
            data_collection_id:
              type: string
          required:
            - type
            - name
            - data_collection_id
      discriminator:
        propertyName: type
    type_:GetConvAiDashboardSettingsResponseModel:
      type: object
      properties:
        charts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:GetConvAiDashboardSettingsResponseModelChartsItem

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.dashboard.settings.get();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.dashboard.settings.get()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/settings/dashboard"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/settings/dashboard")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/settings/dashboard")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/settings/dashboard');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/settings/dashboard");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/settings/dashboard")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update Convai Dashboard Settings

PATCH https://api.elevenlabs.io/v1/convai/settings/dashboard
Content-Type: application/json

Update Convai dashboard settings for the workspace

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/dashboard/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Convai Dashboard Settings
  version: endpoint_conversationalAi/dashboard/settings.update
paths:
  /v1/convai/settings/dashboard:
    patch:
      operationId: update
      summary: Update Convai Dashboard Settings
      description: Update Convai dashboard settings for the workspace
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/dashboard
          - subpackage_conversationalAi/dashboard/settings
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/type_:GetConvAiDashboardSettingsResponseModel
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                charts:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/dashboard/settings:PatchConvAiDashboardSettingsRequestChartsItem
components:
  schemas:
    type_conversationalAi/dashboard/settings:PatchConvAiDashboardSettingsRequestChartsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - call_success
              description: 'Discriminator value: call_success'
            name:
              type: string
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - criteria
              description: 'Discriminator value: criteria'
            name:
              type: string
            criteria_id:
              type: string
          required:
            - type
            - name
            - criteria_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - data_collection
              description: 'Discriminator value: data_collection'
            name:
              type: string
            data_collection_id:
              type: string
          required:
            - type
            - name
            - data_collection_id
      discriminator:
        propertyName: type
    type_:GetConvAiDashboardSettingsResponseModelChartsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - call_success
              description: 'Discriminator value: call_success'
            name:
              type: string
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - criteria
              description: 'Discriminator value: criteria'
            name:
              type: string
            criteria_id:
              type: string
          required:
            - type
            - name
            - criteria_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - data_collection
              description: 'Discriminator value: data_collection'
            name:
              type: string
            data_collection_id:
              type: string
          required:
            - type
            - name
            - data_collection_id
      discriminator:
        propertyName: type
    type_:GetConvAiDashboardSettingsResponseModel:
      type: object
      properties:
        charts:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:GetConvAiDashboardSettingsResponseModelChartsItem

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.dashboard.settings.update({});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.dashboard.settings.update()

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/settings/dashboard"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/settings/dashboard")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/settings/dashboard")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/settings/dashboard', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/settings/dashboard");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/settings/dashboard")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Outbound call via SIP trunk

POST https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call
Content-Type: application/json

Handle an outbound call via SIP trunk

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/sip-trunk/outbound-call

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Handle An Outbound Call Via Sip Trunk
  version: endpoint_conversationalAi/sipTrunk.outbound_call
paths:
  /v1/convai/sip-trunk/outbound-call:
    post:
      operationId: outbound-call
      summary: Handle An Outbound Call Via Sip Trunk
      description: Handle an outbound call via SIP trunk
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/sipTrunk
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:SipTrunkOutboundCallResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                agent_phone_number_id:
                  type: string
                to_number:
                  type: string
                conversation_initiation_client_data:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataRequestInput
              required:
                - agent_id
                - agent_phone_number_id
                - to_number
components:
  schemas:
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue
    type_:SipTrunkOutboundCallResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        conversation_id:
          type: string
        sip_call_id:
          type: string
      required:
        - success
        - message

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.sipTrunk.outboundCall({
        agentId: "agent_id",
        agentPhoneNumberId: "agent_phone_number_id",
        toNumber: "to_number",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.sip_trunk.outbound_call(
    agent_id="agent_id",
    agent_phone_number_id="agent_phone_number_id",
    to_number="to_number"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call', [
  'body' => '{
  "agent_id": "agent_id",
  "agent_phone_number_id": "agent_phone_number_id",
  "to_number": "to_number"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "agent_id": "agent_id",
  "agent_phone_number_id": "agent_phone_number_id",
  "to_number": "to_number"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Outbound call via twilio

POST https://api.elevenlabs.io/v1/convai/twilio/outbound-call
Content-Type: application/json

Handle an outbound call via Twilio

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/twilio/outbound-call

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Handle An Outbound Call Via Twilio
  version: endpoint_conversationalAi/twilio.outbound_call
paths:
  /v1/convai/twilio/outbound-call:
    post:
      operationId: outbound-call
      summary: Handle An Outbound Call Via Twilio
      description: Handle an outbound call via Twilio
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/twilio
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:TwilioOutboundCallResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                agent_phone_number_id:
                  type: string
                to_number:
                  type: string
                conversation_initiation_client_data:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataRequestInput
              required:
                - agent_id
                - agent_phone_number_id
                - to_number
components:
  schemas:
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue
    type_:TwilioOutboundCallResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        conversation_id:
          type: string
        callSid:
          type: string
      required:
        - success
        - message

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.twilio.outboundCall({
        agentId: "agent_id",
        agentPhoneNumberId: "agent_phone_number_id",
        toNumber: "to_number",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.twilio.outbound_call(
    agent_id="agent_id",
    agent_phone_number_id="agent_phone_number_id",
    to_number="to_number"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/twilio/outbound-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/twilio/outbound-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/twilio/outbound-call")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/twilio/outbound-call', [
  'body' => '{
  "agent_id": "agent_id",
  "agent_phone_number_id": "agent_phone_number_id",
  "to_number": "to_number"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/twilio/outbound-call");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"agent_id\": \"agent_id\",\n  \"agent_phone_number_id\": \"agent_phone_number_id\",\n  \"to_number\": \"to_number\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "agent_id": "agent_id",
  "agent_phone_number_id": "agent_phone_number_id",
  "to_number": "to_number"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/twilio/outbound-call")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Register call

POST https://api.elevenlabs.io/v1/convai/twilio/register-call
Content-Type: application/json

Register a Twilio call and return TwiML to connect the call

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/twilio/register-call

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Register A Twilio Call And Return Twiml
  version: endpoint_conversationalAi/twilio.register_call
paths:
  /v1/convai/twilio/register-call:
    post:
      operationId: register-call
      summary: Register A Twilio Call And Return Twiml
      description: Register a Twilio call and return TwiML to connect the call
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/twilio
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                from_number:
                  type: string
                to_number:
                  type: string
                direction:
                  $ref: >-
                    #/components/schemas/type_conversationalAi/twilio:BodyRegisterATwilioCallAndReturnTwiMlV1ConvaiTwilioRegisterCallPostDirection
                conversation_initiation_client_data:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataRequestInput
              required:
                - agent_id
                - from_number
                - to_number
components:
  schemas:
    type_conversationalAi/twilio:BodyRegisterATwilioCallAndReturnTwiMlV1ConvaiTwilioRegisterCallPostDirection:
      type: string
      enum:
        - value: inbound
        - value: outbound
      default: inbound
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.twilio.registerCall({
        agentId: "agent_id",
        fromNumber: "from_number",
        toNumber: "to_number",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.twilio.register_call(
    agent_id="agent_id",
    from_number="from_number",
    to_number="to_number"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/twilio/register-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"agent_id\",\n  \"from_number\": \"from_number\",\n  \"to_number\": \"to_number\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/twilio/register-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"agent_id\",\n  \"from_number\": \"from_number\",\n  \"to_number\": \"to_number\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/twilio/register-call")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"agent_id\",\n  \"from_number\": \"from_number\",\n  \"to_number\": \"to_number\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/twilio/register-call', [
  'body' => '{
  "agent_id": "agent_id",
  "from_number": "from_number",
  "to_number": "to_number"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/twilio/register-call");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"agent_id\": \"agent_id\",\n  \"from_number\": \"from_number\",\n  \"to_number\": \"to_number\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "agent_id": "agent_id",
  "from_number": "from_number",
  "to_number": "to_number"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/twilio/register-call")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List WhatsApp accounts

GET https://api.elevenlabs.io/v1/convai/whatsapp-accounts

List all WhatsApp accounts

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/accounts/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Whatsapp Accounts
  version: endpoint_conversationalAi/whatsappAccounts.list
paths:
  /v1/convai/whatsapp-accounts:
    get:
      operationId: list
      summary: List Whatsapp Accounts
      description: List all WhatsApp accounts
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsappAccounts
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ListWhatsAppAccountsResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetWhatsAppAccountResponse:
      type: object
      properties:
        business_account_id:
          type: string
        phone_number_id:
          type: string
        business_account_name:
          type: string
        phone_number_name:
          type: string
        phone_number:
          type: string
        assigned_agent_id:
          type: string
        assigned_agent_name:
          type: string
      required:
        - business_account_id
        - phone_number_id
        - business_account_name
        - phone_number_name
        - phone_number
    type_:ListWhatsAppAccountsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/type_:GetWhatsAppAccountResponse'
      required:
        - items

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsappAccounts.list();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp_accounts.list()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp-accounts"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/whatsapp-accounts")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/whatsapp-accounts');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp-accounts");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp-accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get WhatsApp account

GET https://api.elevenlabs.io/v1/convai/whatsapp-accounts/{phone_number_id}

Get a WhatsApp account

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/accounts/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Whatsapp Account
  version: endpoint_conversationalAi/whatsappAccounts.get
paths:
  /v1/convai/whatsapp-accounts/{phone_number_id}:
    get:
      operationId: get
      summary: Get Whatsapp Account
      description: Get a WhatsApp account
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsappAccounts
      parameters:
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetWhatsAppAccountResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetWhatsAppAccountResponse:
      type: object
      properties:
        business_account_id:
          type: string
        phone_number_id:
          type: string
        business_account_name:
          type: string
        phone_number_name:
          type: string
        phone_number:
          type: string
        assigned_agent_id:
          type: string
        assigned_agent_name:
          type: string
      required:
        - business_account_id
        - phone_number_id
        - business_account_name
        - phone_number_name
        - phone_number

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsappAccounts.get("phone_number_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp_accounts.get(
    phone_number_id="phone_number_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update WhatsApp account

PATCH https://api.elevenlabs.io/v1/convai/whatsapp-accounts/{phone_number_id}
Content-Type: application/json

Update a WhatsApp account

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/accounts/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Whatsapp Account
  version: endpoint_conversationalAi/whatsappAccounts.update
paths:
  /v1/convai/whatsapp-accounts/{phone_number_id}:
    patch:
      operationId: update
      summary: Update Whatsapp Account
      description: Update a WhatsApp account
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsappAccounts
      parameters:
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                assigned_agent_id:
                  type: string

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsappAccounts.update("phone_number_id", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp_accounts.update(
    phone_number_id="phone_number_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete WhatsApp account

DELETE https://api.elevenlabs.io/v1/convai/whatsapp-accounts/{phone_number_id}

Delete a WhatsApp account

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/accounts/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Whatsapp Account
  version: endpoint_conversationalAi/whatsappAccounts.delete
paths:
  /v1/convai/whatsapp-accounts/{phone_number_id}:
    delete:
      operationId: delete
      summary: Delete Whatsapp Account
      description: Delete a WhatsApp account
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsappAccounts
      parameters:
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsappAccounts.delete("phone_number_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp_accounts.delete(
    phone_number_id="phone_number_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp-accounts/phone_number_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Outbound call via WhatsApp

POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call
Content-Type: application/json

Make an outbound call via WhatsApp

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/outbound-call

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Make An Outbound Call Via Whatsapp
  version: endpoint_conversationalAi/whatsapp.outbound_call
paths:
  /v1/convai/whatsapp/outbound-call:
    post:
      operationId: outbound-call
      summary: Make An Outbound Call Via Whatsapp
      description: Make an outbound call via WhatsApp
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsapp
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:WhatsAppOutboundCallResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                whatsapp_phone_number_id:
                  type: string
                whatsapp_user_id:
                  type: string
                whatsapp_call_permission_request_template_name:
                  type: string
                whatsapp_call_permission_request_template_language_code:
                  type: string
                agent_id:
                  type: string
                conversation_initiation_client_data:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataRequestInput
              required:
                - whatsapp_phone_number_id
                - whatsapp_user_id
                - whatsapp_call_permission_request_template_name
                - whatsapp_call_permission_request_template_language_code
                - agent_id
components:
  schemas:
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue
    type_:WhatsAppOutboundCallResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        conversation_id:
          type: string
      required:
        - success
        - message

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsapp.outboundCall({
        whatsappPhoneNumberId: "whatsapp_phone_number_id",
        whatsappUserId: "whatsapp_user_id",
        whatsappCallPermissionRequestTemplateName: "whatsapp_call_permission_request_template_name",
        whatsappCallPermissionRequestTemplateLanguageCode: "whatsapp_call_permission_request_template_language_code",
        agentId: "agent_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp.outbound_call(
    whatsapp_phone_number_id="whatsapp_phone_number_id",
    whatsapp_user_id="whatsapp_user_id",
    whatsapp_call_permission_request_template_name="whatsapp_call_permission_request_template_name",
    whatsapp_call_permission_request_template_language_code="whatsapp_call_permission_request_template_language_code",
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call"

	payload := strings.NewReader("{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"whatsapp_call_permission_request_template_name\": \"whatsapp_call_permission_request_template_name\",\n  \"whatsapp_call_permission_request_template_language_code\": \"whatsapp_call_permission_request_template_language_code\",\n  \"agent_id\": \"agent_id\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"whatsapp_call_permission_request_template_name\": \"whatsapp_call_permission_request_template_name\",\n  \"whatsapp_call_permission_request_template_language_code\": \"whatsapp_call_permission_request_template_language_code\",\n  \"agent_id\": \"agent_id\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call")
  .header("Content-Type", "application/json")
  .body("{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"whatsapp_call_permission_request_template_name\": \"whatsapp_call_permission_request_template_name\",\n  \"whatsapp_call_permission_request_template_language_code\": \"whatsapp_call_permission_request_template_language_code\",\n  \"agent_id\": \"agent_id\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call', [
  'body' => '{
  "whatsapp_phone_number_id": "whatsapp_phone_number_id",
  "whatsapp_user_id": "whatsapp_user_id",
  "whatsapp_call_permission_request_template_name": "whatsapp_call_permission_request_template_name",
  "whatsapp_call_permission_request_template_language_code": "whatsapp_call_permission_request_template_language_code",
  "agent_id": "agent_id"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"whatsapp_call_permission_request_template_name\": \"whatsapp_call_permission_request_template_name\",\n  \"whatsapp_call_permission_request_template_language_code\": \"whatsapp_call_permission_request_template_language_code\",\n  \"agent_id\": \"agent_id\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "whatsapp_phone_number_id": "whatsapp_phone_number_id",
  "whatsapp_user_id": "whatsapp_user_id",
  "whatsapp_call_permission_request_template_name": "whatsapp_call_permission_request_template_name",
  "whatsapp_call_permission_request_template_language_code": "whatsapp_call_permission_request_template_language_code",
  "agent_id": "agent_id"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Outbound message via WhatsApp

POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message
Content-Type: application/json

Send an outbound message via WhatsApp

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/whats-app/outbound-message

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Send An Outbound Message Via Whatsapp
  version: endpoint_conversationalAi/whatsapp.outbound_message
paths:
  /v1/convai/whatsapp/outbound-message:
    post:
      operationId: outbound-message
      summary: Send An Outbound Message Via Whatsapp
      description: Send an outbound message via WhatsApp
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/whatsapp
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:WhatsAppOutboundMessageResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                whatsapp_phone_number_id:
                  type: string
                whatsapp_user_id:
                  type: string
                template_name:
                  type: string
                template_language_code:
                  type: string
                template_params:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/whatsapp:BodySendAnOutboundMessageViaWhatsAppV1ConvaiWhatsappOutboundMessagePostTemplateParamsItem
                agent_id:
                  type: string
                conversation_initiation_client_data:
                  $ref: >-
                    #/components/schemas/type_:ConversationInitiationClientDataRequestInput
              required:
                - whatsapp_phone_number_id
                - whatsapp_user_id
                - template_name
                - template_language_code
                - template_params
                - agent_id
components:
  schemas:
    type_:WhatsAppTemplateTextParam:
      type: object
      properties:
        parameter_name:
          type: string
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: text
        text:
          type: string
      required:
        - text
    type_:WhatsAppTemplateDocumentParamDetails:
      type: object
      properties:
        link:
          type: string
        filename:
          type: string
      required:
        - link
    type_:WhatsAppTemplateImageParamDetails:
      type: object
      properties:
        link:
          type: string
      required:
        - link
    type_:WhatsAppTemplateLocationParamDetails:
      type: object
      properties:
        latitude:
          type: string
        longitude:
          type: string
        name:
          type: string
        address:
          type: string
      required:
        - latitude
        - longitude
        - name
        - address
    type_:WhatsAppTemplateHeaderComponentParamsParametersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - document
              description: 'Discriminator value: document'
            document:
              $ref: '#/components/schemas/type_:WhatsAppTemplateDocumentParamDetails'
          required:
            - type
            - document
        - type: object
          properties:
            type:
              type: string
              enum:
                - image
              description: 'Discriminator value: image'
            image:
              $ref: '#/components/schemas/type_:WhatsAppTemplateImageParamDetails'
          required:
            - type
            - image
        - type: object
          properties:
            type:
              type: string
              enum:
                - location
              description: 'Discriminator value: location'
            location:
              $ref: '#/components/schemas/type_:WhatsAppTemplateLocationParamDetails'
          required:
            - type
            - location
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
            parameter_name:
              type: string
            text:
              type: string
          required:
            - type
            - text
      discriminator:
        propertyName: type
    type_conversationalAi/whatsapp:BodySendAnOutboundMessageViaWhatsAppV1ConvaiWhatsappOutboundMessagePostTemplateParamsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - body
              description: 'Discriminator value: body'
            parameters:
              type: array
              items:
                $ref: '#/components/schemas/type_:WhatsAppTemplateTextParam'
          required:
            - type
            - parameters
        - type: object
          properties:
            type:
              type: string
              enum:
                - button
              description: 'Discriminator value: button'
            parameters:
              type: array
              items:
                $ref: '#/components/schemas/type_:WhatsAppTemplateTextParam'
            index:
              type: integer
            sub_type:
              type: string
          required:
            - type
            - parameters
            - index
            - sub_type
        - type: object
          properties:
            type:
              type: string
              enum:
                - header
              description: 'Discriminator value: header'
            parameters:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WhatsAppTemplateHeaderComponentParamsParametersItem
          required:
            - type
            - parameters
      discriminator:
        propertyName: type
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue
    type_:WhatsAppOutboundMessageResponse:
      type: object
      properties:
        conversation_id:
          type: string
      required:
        - conversation_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.whatsapp.outboundMessage({
        whatsappPhoneNumberId: "whatsapp_phone_number_id",
        whatsappUserId: "whatsapp_user_id",
        templateName: "template_name",
        templateLanguageCode: "template_language_code",
        templateParams: [
            {
                type: "body",
                parameters: [
                    {
                        text: "text",
                    },
                ],
            },
        ],
        agentId: "agent_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.whatsapp.outbound_message(
    whatsapp_phone_number_id="whatsapp_phone_number_id",
    whatsapp_user_id="whatsapp_user_id",
    template_name="template_name",
    template_language_code="template_language_code",
    template_params=[
        {
            "type": "body",
            "parameters": [
                {
                    "text": "text"
                }
            ]
        }
    ],
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message"

	payload := strings.NewReader("{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"template_name\": \"template_name\",\n  \"template_language_code\": \"template_language_code\",\n  \"template_params\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"text\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"agent_id\": \"agent_id\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"template_name\": \"template_name\",\n  \"template_language_code\": \"template_language_code\",\n  \"template_params\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"text\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"agent_id\": \"agent_id\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message")
  .header("Content-Type", "application/json")
  .body("{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"template_name\": \"template_name\",\n  \"template_language_code\": \"template_language_code\",\n  \"template_params\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"text\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"agent_id\": \"agent_id\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message', [
  'body' => '{
  "whatsapp_phone_number_id": "whatsapp_phone_number_id",
  "whatsapp_user_id": "whatsapp_user_id",
  "template_name": "template_name",
  "template_language_code": "template_language_code",
  "template_params": [
    {
      "type": "body",
      "parameters": [
        {
          "text": "text"
        }
      ]
    }
  ],
  "agent_id": "agent_id"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"whatsapp_phone_number_id\": \"whatsapp_phone_number_id\",\n  \"whatsapp_user_id\": \"whatsapp_user_id\",\n  \"template_name\": \"template_name\",\n  \"template_language_code\": \"template_language_code\",\n  \"template_params\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"text\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"agent_id\": \"agent_id\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "whatsapp_phone_number_id": "whatsapp_phone_number_id",
  "whatsapp_user_id": "whatsapp_user_id",
  "template_name": "template_name",
  "template_language_code": "template_language_code",
  "template_params": [
    [
      "type": "body",
      "parameters": [["text": "text"]]
    ]
  ],
  "agent_id": "agent_id"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Submit batch calling job

POST https://api.elevenlabs.io/v1/convai/batch-calling/submit
Content-Type: application/json

Submit a batch call request to schedule calls for multiple recipients.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Submit A Batch Call Request.
  version: endpoint_conversationalAi/batchCalls.create
paths:
  /v1/convai/batch-calling/submit:
    post:
      operationId: create
      summary: Submit A Batch Call Request.
      description: Submit a batch call request to schedule calls for multiple recipients.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:BatchCallResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                call_name:
                  type: string
                agent_id:
                  type: string
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:OutboundCallRecipient'
                scheduled_time_unix:
                  type: integer
                agent_phone_number_id:
                  type: string
                whatsapp_params:
                  $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
                timezone:
                  type: string
              required:
                - call_name
                - agent_id
                - recipients
components:
  schemas:
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataRequestInput:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataRequestInputDynamicVariablesValue
    type_:OutboundCallRecipient:
      type: object
      properties:
        id:
          type: string
        phone_number:
          type: string
        whatsapp_user_id:
          type: string
        conversation_initiation_client_data:
          $ref: >-
            #/components/schemas/type_:ConversationInitiationClientDataRequestInput
    type_:BatchCallWhatsAppParams:
      type: object
      properties:
        whatsapp_phone_number_id:
          type: string
        whatsapp_call_permission_request_template_name:
          type: string
        whatsapp_call_permission_request_template_language_code:
          type: string
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:BatchCallStatus:
      type: string
      enum:
        - value: pending
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
    type_:BatchCallResponse:
      type: object
      properties:
        id:
          type: string
        phone_number_id:
          type: string
        phone_provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
        whatsapp_params:
          $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
        name:
          type: string
        agent_id:
          type: string
        created_at_unix:
          type: integer
        scheduled_time_unix:
          type: integer
        timezone:
          type: string
        total_calls_dispatched:
          type: integer
          default: 0
        total_calls_scheduled:
          type: integer
          default: 0
        total_calls_finished:
          type: integer
          default: 0
        last_updated_at_unix:
          type: integer
        status:
          $ref: '#/components/schemas/type_:BatchCallStatus'
        retry_count:
          type: integer
          default: 0
        agent_name:
          type: string
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - total_calls_dispatched
        - total_calls_scheduled
        - total_calls_finished
        - last_updated_at_unix
        - status
        - retry_count
        - agent_name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.create({
        callName: "call_name",
        agentId: "agent_id",
        recipients: [
            {},
        ],
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.create(
    call_name="call_name",
    agent_id="agent_id",
    recipients=[
        {}
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/submit"

	payload := strings.NewReader("{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/submit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/batch-calling/submit")
  .header("Content-Type", "application/json")
  .body("{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/batch-calling/submit', [
  'body' => '{
  "call_name": "call_name",
  "agent_id": "agent_id",
  "recipients": [
    {}
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/submit");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "call_name": "call_name",
  "agent_id": "agent_id",
  "recipients": [[]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/submit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List workspace batch calling jobs

GET https://api.elevenlabs.io/v1/convai/batch-calling/workspace

Get all batch calls for the current workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get All Batch Calls For A Workspace.
  version: endpoint_conversationalAi/batchCalls.list
paths:
  /v1/convai/batch-calling/workspace:
    get:
      operationId: list
      summary: Get All Batch Calls For A Workspace.
      description: Get all batch calls for the current workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: last_doc
          in: query
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:WorkspaceBatchCallsResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:BatchCallWhatsAppParams:
      type: object
      properties:
        whatsapp_phone_number_id:
          type: string
        whatsapp_call_permission_request_template_name:
          type: string
        whatsapp_call_permission_request_template_language_code:
          type: string
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
    type_:BatchCallStatus:
      type: string
      enum:
        - value: pending
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
    type_:BatchCallResponse:
      type: object
      properties:
        id:
          type: string
        phone_number_id:
          type: string
        phone_provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
        whatsapp_params:
          $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
        name:
          type: string
        agent_id:
          type: string
        created_at_unix:
          type: integer
        scheduled_time_unix:
          type: integer
        timezone:
          type: string
        total_calls_dispatched:
          type: integer
          default: 0
        total_calls_scheduled:
          type: integer
          default: 0
        total_calls_finished:
          type: integer
          default: 0
        last_updated_at_unix:
          type: integer
        status:
          $ref: '#/components/schemas/type_:BatchCallStatus'
        retry_count:
          type: integer
          default: 0
        agent_name:
          type: string
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - total_calls_dispatched
        - total_calls_scheduled
        - total_calls_finished
        - last_updated_at_unix
        - status
        - retry_count
        - agent_name
    type_:WorkspaceBatchCallsResponse:
      type: object
      properties:
        batch_calls:
          type: array
          items:
            $ref: '#/components/schemas/type_:BatchCallResponse'
        next_doc:
          type: string
          description: The next document, used to paginate through the batch calls
        has_more:
          type: boolean
          default: false
          description: Whether there are more batch calls to paginate through
      required:
        - batch_calls

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.list({
        limit: 1,
        lastDoc: "last_doc",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.list(
    limit=1,
    last_doc="last_doc"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/workspace?limit=1&last_doc=last_doc")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get batch call information

GET https://api.elevenlabs.io/v1/convai/batch-calling/{batch_id}

Get detailed information about a batch call including all recipients.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get A Batch Call By Id.
  version: endpoint_conversationalAi/batchCalls.get
paths:
  /v1/convai/batch-calling/{batch_id}:
    get:
      operationId: get
      summary: Get A Batch Call By Id.
      description: Get detailed information about a batch call including all recipients.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:BatchCallDetailedResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:BatchCallWhatsAppParams:
      type: object
      properties:
        whatsapp_phone_number_id:
          type: string
        whatsapp_call_permission_request_template_name:
          type: string
        whatsapp_call_permission_request_template_language_code:
          type: string
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
    type_:BatchCallStatus:
      type: string
      enum:
        - value: pending
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
    type_:BatchCallRecipientStatus:
      type: string
      enum:
        - value: pending
        - value: dispatched
        - value: initiated
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
        - value: voicemail
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideOutput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideOutput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideOutput'
          description: Agent specific configuration
    type_:ConversationInitiationSource:
      type: string
      enum:
        - value: unknown
        - value: android_sdk
        - value: node_js_sdk
        - value: react_native_sdk
        - value: react_sdk
        - value: js_sdk
        - value: python_sdk
        - value: widget
        - value: sip_trunk
        - value: twilio
        - value: genesys
        - value: swift_sdk
        - value: whatsapp
        - value: flutter_sdk
        - value: zendesk_integration
        - value: slack_integration
    type_:ConversationInitiationSourceInfo:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_:ConversationInitiationSource'
          description: Source of the conversation initiation
        version:
          type: string
          description: The SDK version number
    type_:ConversationInitiationClientDataInternalDynamicVariablesValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:ConversationInitiationClientDataInternal:
      type: object
      properties:
        conversation_config_override:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideOutput'
        custom_llm_extra_body:
          type: object
          additionalProperties:
            description: Any type
        user_id:
          type: string
          description: >-
            ID of the end user participating in this conversation (for agent
            owner's user identification)
        source_info:
          $ref: '#/components/schemas/type_:ConversationInitiationSourceInfo'
        dynamic_variables:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ConversationInitiationClientDataInternalDynamicVariablesValue
    type_:OutboundCallRecipientResponseModel:
      type: object
      properties:
        id:
          type: string
        phone_number:
          type: string
        whatsapp_user_id:
          type: string
        status:
          $ref: '#/components/schemas/type_:BatchCallRecipientStatus'
        created_at_unix:
          type: integer
        updated_at_unix:
          type: integer
        conversation_id:
          type: string
        conversation_initiation_client_data:
          $ref: '#/components/schemas/type_:ConversationInitiationClientDataInternal'
      required:
        - id
        - status
        - created_at_unix
        - updated_at_unix
    type_:BatchCallDetailedResponse:
      type: object
      properties:
        id:
          type: string
        phone_number_id:
          type: string
        phone_provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
        whatsapp_params:
          $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
        name:
          type: string
        agent_id:
          type: string
        created_at_unix:
          type: integer
        scheduled_time_unix:
          type: integer
        timezone:
          type: string
        total_calls_dispatched:
          type: integer
          default: 0
        total_calls_scheduled:
          type: integer
          default: 0
        total_calls_finished:
          type: integer
          default: 0
        last_updated_at_unix:
          type: integer
        status:
          $ref: '#/components/schemas/type_:BatchCallStatus'
        retry_count:
          type: integer
          default: 0
        agent_name:
          type: string
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/type_:OutboundCallRecipientResponseModel'
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - total_calls_dispatched
        - total_calls_scheduled
        - total_calls_finished
        - last_updated_at_unix
        - status
        - retry_count
        - agent_name
        - recipients

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.get("batch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.get(
    batch_id="batch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/batch-calling/batch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Cancel batch calling job

POST https://api.elevenlabs.io/v1/convai/batch-calling/{batch_id}/cancel

Cancel a running batch call and set all recipients to cancelled status.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/cancel

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Cancel A Batch Call.
  version: endpoint_conversationalAi/batchCalls.cancel
paths:
  /v1/convai/batch-calling/{batch_id}/cancel:
    post:
      operationId: cancel
      summary: Cancel A Batch Call.
      description: Cancel a running batch call and set all recipients to cancelled status.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:BatchCallResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:BatchCallWhatsAppParams:
      type: object
      properties:
        whatsapp_phone_number_id:
          type: string
        whatsapp_call_permission_request_template_name:
          type: string
        whatsapp_call_permission_request_template_language_code:
          type: string
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
    type_:BatchCallStatus:
      type: string
      enum:
        - value: pending
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
    type_:BatchCallResponse:
      type: object
      properties:
        id:
          type: string
        phone_number_id:
          type: string
        phone_provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
        whatsapp_params:
          $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
        name:
          type: string
        agent_id:
          type: string
        created_at_unix:
          type: integer
        scheduled_time_unix:
          type: integer
        timezone:
          type: string
        total_calls_dispatched:
          type: integer
          default: 0
        total_calls_scheduled:
          type: integer
          default: 0
        total_calls_finished:
          type: integer
          default: 0
        last_updated_at_unix:
          type: integer
        status:
          $ref: '#/components/schemas/type_:BatchCallStatus'
        retry_count:
          type: integer
          default: 0
        agent_name:
          type: string
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - total_calls_dispatched
        - total_calls_scheduled
        - total_calls_finished
        - last_updated_at_unix
        - status
        - retry_count
        - agent_name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.cancel("batch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.cancel(
    batch_id="batch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/cancel")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Retry batch calling job

POST https://api.elevenlabs.io/v1/convai/batch-calling/{batch_id}/retry

Retry a batch call, calling failed and no-response recipients again.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/retry

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retry A Batch Call.
  version: endpoint_conversationalAi/batchCalls.retry
paths:
  /v1/convai/batch-calling/{batch_id}/retry:
    post:
      operationId: retry
      summary: Retry A Batch Call.
      description: Retry a batch call, calling failed and no-response recipients again.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:BatchCallResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:TelephonyProvider:
      type: string
      enum:
        - value: twilio
        - value: sip_trunk
    type_:BatchCallWhatsAppParams:
      type: object
      properties:
        whatsapp_phone_number_id:
          type: string
        whatsapp_call_permission_request_template_name:
          type: string
        whatsapp_call_permission_request_template_language_code:
          type: string
      required:
        - whatsapp_call_permission_request_template_name
        - whatsapp_call_permission_request_template_language_code
    type_:BatchCallStatus:
      type: string
      enum:
        - value: pending
        - value: in_progress
        - value: completed
        - value: failed
        - value: cancelled
    type_:BatchCallResponse:
      type: object
      properties:
        id:
          type: string
        phone_number_id:
          type: string
        phone_provider:
          $ref: '#/components/schemas/type_:TelephonyProvider'
        whatsapp_params:
          $ref: '#/components/schemas/type_:BatchCallWhatsAppParams'
        name:
          type: string
        agent_id:
          type: string
        created_at_unix:
          type: integer
        scheduled_time_unix:
          type: integer
        timezone:
          type: string
        total_calls_dispatched:
          type: integer
          default: 0
        total_calls_scheduled:
          type: integer
          default: 0
        total_calls_finished:
          type: integer
          default: 0
        last_updated_at_unix:
          type: integer
        status:
          $ref: '#/components/schemas/type_:BatchCallStatus'
        retry_count:
          type: integer
          default: 0
        agent_name:
          type: string
      required:
        - id
        - name
        - agent_id
        - created_at_unix
        - scheduled_time_unix
        - total_calls_dispatched
        - total_calls_scheduled
        - total_calls_finished
        - last_updated_at_unix
        - status
        - retry_count
        - agent_name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.retry("batch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.retry(
    batch_id="batch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id/retry")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete batch calling job

DELETE https://api.elevenlabs.io/v1/convai/batch-calling/{batch_id}

Permanently delete a batch call and all recipient records. Conversations remain in history.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete A Batch Call.
  version: endpoint_conversationalAi/batchCalls.delete
paths:
  /v1/convai/batch-calling/{batch_id}:
    delete:
      operationId: delete
      summary: Delete A Batch Call.
      description: >-
        Permanently delete a batch call and all recipient records. Conversations
        remain in history.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/batchCalls
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.batchCalls.delete("batch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.batch_calls.delete(
    batch_id="batch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/batch-calling/batch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/batch_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/batch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Calculate expected LLM usage

POST https://api.elevenlabs.io/v1/convai/llm-usage/calculate
Content-Type: application/json

Returns a list of LLM models and the expected cost for using them based on the provided values.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/llm-usage/calculate

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Calculate Expected Llm Usage
  version: endpoint_conversationalAi/llmUsage.calculate
paths:
  /v1/convai/llm-usage/calculate:
    post:
      operationId: calculate
      summary: Calculate Expected Llm Usage
      description: >-
        Returns a list of LLM models and the expected cost for using them based
        on the provided values.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/llmUsage
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:LlmUsageCalculatorResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt_length:
                  type: integer
                  description: Length of the prompt in characters.
                number_of_pages:
                  type: integer
                  description: >-
                    Pages of content in PDF documents or URLs in the agent's
                    knowledge base.
                rag_enabled:
                  type: boolean
                  description: Whether RAG is enabled.
              required:
                - prompt_length
                - number_of_pages
                - rag_enabled
components:
  schemas:
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:LlmUsageCalculatorLlmResponseModel:
      type: object
      properties:
        llm:
          $ref: '#/components/schemas/type_:Llm'
        price_per_minute:
          type: number
          format: double
      required:
        - llm
        - price_per_minute
    type_:LlmUsageCalculatorResponseModel:
      type: object
      properties:
        llm_prices:
          type: array
          items:
            $ref: '#/components/schemas/type_:LlmUsageCalculatorLlmResponseModel'
      required:
        - llm_prices

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.llmUsage.calculate({
        promptLength: 1,
        numberOfPages: 1,
        ragEnabled: true,
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.llm_usage.calculate(
    prompt_length=1,
    number_of_pages=1,
    rag_enabled=True
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/llm-usage/calculate"

	payload := strings.NewReader("{\n  \"prompt_length\": 1,\n  \"number_of_pages\": 1,\n  \"rag_enabled\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/llm-usage/calculate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt_length\": 1,\n  \"number_of_pages\": 1,\n  \"rag_enabled\": true\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/llm-usage/calculate")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt_length\": 1,\n  \"number_of_pages\": 1,\n  \"rag_enabled\": true\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/llm-usage/calculate', [
  'body' => '{
  "prompt_length": 1,
  "number_of_pages": 1,
  "rag_enabled": true
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/llm-usage/calculate");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"prompt_length\": 1,\n  \"number_of_pages\": 1,\n  \"rag_enabled\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "prompt_length": 1,
  "number_of_pages": 1,
  "rag_enabled": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/llm-usage/calculate")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create MCP server

POST https://api.elevenlabs.io/v1/convai/mcp-servers
Content-Type: application/json

Create a new MCP server configuration in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Mcp Server
  version: endpoint_conversationalAi/mcpServers.create
paths:
  /v1/convai/mcp-servers:
    post:
      operationId: create
      summary: Create Mcp Server
      description: Create a new MCP server configuration in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  $ref: '#/components/schemas/type_:McpServerConfigInput'
                  description: Configuration details for the MCP Server.
              required:
                - config
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigInputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigInputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigInput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigInputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigInputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:McpServerConfigInputRequestHeadersValue'
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.create({
        config: {
            url: "url",
            name: "name",
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.create(
    config={
        "url": "url",
        "name": "name"
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers"

	payload := strings.NewReader("{\n  \"config\": {\n    \"url\": \"url\",\n    \"name\": \"name\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"config\": {\n    \"url\": \"url\",\n    \"name\": \"name\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/mcp-servers")
  .header("Content-Type", "application/json")
  .body("{\n  \"config\": {\n    \"url\": \"url\",\n    \"name\": \"name\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/mcp-servers', [
  'body' => '{
  "config": {
    "url": "url",
    "name": "name"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"config\": {\n    \"url\": \"url\",\n    \"name\": \"name\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["config": [
    "url": "url",
    "name": "name"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete MCP server

DELETE https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}

Delete a specific MCP server configuration from the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Mcp Server
  version: endpoint_conversationalAi/mcpServers.delete
paths:
  /v1/convai/mcp-servers/{mcp_server_id}:
    delete:
      operationId: delete
      summary: Delete Mcp Server
      description: Delete a specific MCP server configuration from the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.delete("mcp_server_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.delete(
    mcp_server_id="mcp_server_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List MCP servers

GET https://api.elevenlabs.io/v1/convai/mcp-servers

Retrieve all MCP server configurations available in the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Mcp Servers
  version: endpoint_conversationalAi/mcpServers.list
paths:
  /v1/convai/mcp-servers:
    get:
      operationId: list
      summary: List Mcp Servers
      description: Retrieve all MCP server configurations available in the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
      parameters:
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServersResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata
    type_:McpServersResponseModel:
      type: object
      properties:
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpServerResponseModel'
      required:
        - mcp_servers

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.list();
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.list()

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/mcp-servers")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/mcp-servers');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get MCP server

GET https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}

Retrieve a specific MCP server configuration from the workspace.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Mcp Server
  version: endpoint_conversationalAi/mcpServers.get
paths:
  /v1/convai/mcp-servers/{mcp_server_id}:
    get:
      operationId: get
      summary: Get Mcp Server
      description: Retrieve a specific MCP server configuration from the workspace.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.get("mcp_server_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.get(
    mcp_server_id="mcp_server_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# List MCP server tools

GET https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tools

Retrieve all tools available for a specific MCP server configuration.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/list-tools

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Mcp Server Tools
  version: endpoint_conversationalAi/mcpServers/tools.list
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tools:
    get:
      operationId: list
      summary: List Mcp Server Tools
      description: Retrieve all tools available for a specific MCP server configuration.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/tools
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ListMcpToolsResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ToolAnnotations:
      type: object
      properties:
        title:
          type: string
        readOnlyHint:
          type: boolean
        destructiveHint:
          type: boolean
        idempotentHint:
          type: boolean
        openWorldHint:
          type: boolean
    type_:Tool:
      type: object
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
        inputSchema:
          type: object
          additionalProperties:
            description: Any type
        outputSchema:
          type: object
          additionalProperties:
            description: Any type
        annotations:
          $ref: '#/components/schemas/type_:ToolAnnotations'
        _meta:
          type: object
          additionalProperties:
            description: Any type
      required:
        - name
        - inputSchema
    type_:ListMcpToolsResponseModel:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/type_:Tool'
          description: A list of tools available on the MCP server.
        error_message:
          type: string
          description: Error message if the operation was not successful.
      required:
        - success
        - tools

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.tools.list("mcp_server_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tools.list(
    mcp_server_id="mcp_server_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tools")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update MCP server configuration

PATCH https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}
Content-Type: application/json

Update the configuration settings for an MCP server.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Mcp Server Configuration
  version: endpoint_conversationalAi/mcpServers.update
paths:
  /v1/convai/mcp-servers/{mcp_server_id}:
    patch:
      operationId: update
      summary: Update Mcp Server Configuration
      description: Update the configuration settings for an MCP server.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                approval_policy:
                  $ref: '#/components/schemas/type_:McpApprovalPolicy'
                  description: The approval mode to set for the MCP server
                force_pre_tool_speech:
                  type: boolean
                  description: >-
                    If set, overrides the server's force_pre_tool_speech setting
                    for this tool
                disable_interruptions:
                  type: boolean
                  description: >-
                    If set, overrides the server's disable_interruptions setting
                    for this tool
                tool_call_sound:
                  $ref: '#/components/schemas/type_:ToolCallSoundType'
                  description: >-
                    Predefined tool call sound type to play during tool
                    execution for all tools from this MCP server
                tool_call_sound_behavior:
                  $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
                  description: >-
                    Determines when the tool call sound should play for all
                    tools from this MCP server
                execution_mode:
                  $ref: '#/components/schemas/type_:ToolExecutionMode'
                  description: >-
                    If set, overrides the server's execution_mode setting for
                    this tool
                request_headers:
                  type: object
                  additionalProperties:
                    $ref: >-
                      #/components/schemas/type_conversationalAi/mcpServers:McpServerConfigUpdateRequestModelRequestHeadersValue
                  description: The headers to include in requests to the MCP server
                disable_compression:
                  type: boolean
                  description: Whether to disable HTTP compression for this MCP server
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_conversationalAi/mcpServers:McpServerConfigUpdateRequestModelRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.update("mcp_server_id", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.update(
    mcp_server_id="mcp_server_id"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update MCP server approval policy

PATCH https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/approval-policy
Content-Type: application/json

Update the approval policy configuration for an MCP server. DEPRECATED: Use PATCH /mcp-servers/{id} endpoint instead.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/approval-policies/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Mcp Server Approval Policy
  version: endpoint_conversationalAi/mcpServers/approvalPolicy.update
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/approval-policy:
    patch:
      operationId: update
      summary: Update Mcp Server Approval Policy
      description: >-
        Update the approval policy configuration for an MCP server. DEPRECATED:
        Use PATCH /mcp-servers/{id} endpoint instead.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/approvalPolicy
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                approval_policy:
                  $ref: '#/components/schemas/type_:McpApprovalPolicy'
                  description: The approval mode to set for the MCP server
              required:
                - approval_policy
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.approvalPolicy.update("mcp_server_id", {
        approvalPolicy: "auto_approve_all",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.approval_policy.update(
    mcp_server_id="mcp_server_id",
    approval_policy="auto_approve_all"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy"

	payload := strings.NewReader("{\n  \"approval_policy\": \"auto_approve_all\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"approval_policy\": \"auto_approve_all\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy")
  .header("Content-Type", "application/json")
  .body("{\n  \"approval_policy\": \"auto_approve_all\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy', [
  'body' => '{
  "approval_policy": "auto_approve_all"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"approval_policy\": \"auto_approve_all\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["approval_policy": "auto_approve_all"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/approval-policy")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create MCP server tool approval

POST https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-approvals
Content-Type: application/json

Add approval for a specific MCP tool when using per-tool approval mode.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/approval-policies/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Mcp Server Tool Approval
  version: endpoint_conversationalAi/mcpServers/toolApprovals.create
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-approvals:
    post:
      operationId: create
      summary: Create Mcp Server Tool Approval
      description: Add approval for a specific MCP tool when using per-tool approval mode.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolApprovals
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tool_name:
                  type: string
                  description: The name of the MCP tool
                tool_description:
                  type: string
                  description: The description of the MCP tool
                input_schema:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: >-
                    The input schema of the MCP tool (the schema defined on the
                    MCP server before ElevenLabs does any extra processing)
                approval_policy:
                  $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
                  description: The tool-level approval policy
              required:
                - tool_name
                - tool_description
components:
  schemas:
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolApprovals.create("mcp_server_id", {
        toolName: "tool_name",
        toolDescription: "tool_description",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_approvals.create(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name",
    tool_description="tool_description"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals"

	payload := strings.NewReader("{\n  \"tool_name\": \"tool_name\",\n  \"tool_description\": \"tool_description\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool_name\": \"tool_name\",\n  \"tool_description\": \"tool_description\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_name\": \"tool_name\",\n  \"tool_description\": \"tool_description\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals', [
  'body' => '{
  "tool_name": "tool_name",
  "tool_description": "tool_description"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tool_name\": \"tool_name\",\n  \"tool_description\": \"tool_description\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "tool_name": "tool_name",
  "tool_description": "tool_description"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete MCP server tool approval

DELETE https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-approvals/{tool_name}

Remove approval for a specific MCP tool when using per-tool approval mode.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/approval-policies/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Mcp Server Tool Approval
  version: endpoint_conversationalAi/mcpServers/toolApprovals.delete
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-approvals/{tool_name}:
    delete:
      operationId: delete
      summary: Delete Mcp Server Tool Approval
      description: >-
        Remove approval for a specific MCP tool when using per-tool approval
        mode.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolApprovals
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: tool_name
          in: path
          description: Name of the MCP tool to remove approval for.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolApprovals.delete("mcp_server_id", "tool_name");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_approvals.delete(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-approvals/tool_name")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create configuration override

POST https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-configs
Content-Type: application/json

Create configuration overrides for a specific MCP tool.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/tool-configuration/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Mcp Tool Configuration Override
  version: endpoint_conversationalAi/mcpServers/toolConfigs.create
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-configs:
    post:
      operationId: create
      summary: Create Mcp Tool Configuration Override
      description: Create configuration overrides for a specific MCP tool.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolConfigs
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '409':
          description: Tool config override already exists
          content: {}
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force_pre_tool_speech:
                  type: boolean
                  description: >-
                    If set, overrides the server's force_pre_tool_speech setting
                    for this tool
                disable_interruptions:
                  type: boolean
                  description: >-
                    If set, overrides the server's disable_interruptions setting
                    for this tool
                tool_call_sound:
                  $ref: '#/components/schemas/type_:ToolCallSoundType'
                  description: >-
                    If set, overrides the server's tool_call_sound setting for
                    this tool
                tool_call_sound_behavior:
                  $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
                  description: >-
                    If set, overrides the server's tool_call_sound_behavior
                    setting for this tool
                execution_mode:
                  $ref: '#/components/schemas/type_:ToolExecutionMode'
                  description: >-
                    If set, overrides the server's execution_mode setting for
                    this tool
                assignments:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:DynamicVariableAssignment'
                  description: Dynamic variable assignments for this MCP tool
                tool_name:
                  type: string
                  description: The name of the MCP tool
              required:
                - tool_name
components:
  schemas:
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolConfigs.create("mcp_server_id", {
        toolName: "tool_name",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_configs.create(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs"

	payload := strings.NewReader("{\n  \"tool_name\": \"tool_name\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool_name\": \"tool_name\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_name\": \"tool_name\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs', [
  'body' => '{
  "tool_name": "tool_name"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tool_name\": \"tool_name\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["tool_name": "tool_name"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get configuration override

GET https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}

Retrieve configuration overrides for a specific MCP tool.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/tool-configuration/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Mcp Tool Configuration Override
  version: endpoint_conversationalAi/mcpServers/toolConfigs.get
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}:
    get:
      operationId: get
      summary: Get Mcp Tool Configuration Override
      description: Retrieve configuration overrides for a specific MCP tool.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolConfigs
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: tool_name
          in: path
          description: Name of the MCP tool to retrieve config overrides for.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpToolConfigOverride'
        '404':
          description: Tool config override not found
          content: {}
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolConfigs.get("mcp_server_id", "tool_name");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_configs.get(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update configuration override

PATCH https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}
Content-Type: application/json

Update configuration overrides for a specific MCP tool.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/tool-configuration/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Mcp Tool Configuration Override
  version: endpoint_conversationalAi/mcpServers/toolConfigs.update
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}:
    patch:
      operationId: update
      summary: Update Mcp Tool Configuration Override
      description: Update configuration overrides for a specific MCP tool.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolConfigs
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: tool_name
          in: path
          description: Name of the MCP tool to update config overrides for.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '404':
          description: Tool config override not found
          content: {}
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force_pre_tool_speech:
                  type: boolean
                  description: >-
                    If set, overrides the server's force_pre_tool_speech setting
                    for this tool
                disable_interruptions:
                  type: boolean
                  description: >-
                    If set, overrides the server's disable_interruptions setting
                    for this tool
                tool_call_sound:
                  $ref: '#/components/schemas/type_:ToolCallSoundType'
                  description: >-
                    If set, overrides the server's tool_call_sound setting for
                    this tool
                tool_call_sound_behavior:
                  $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
                  description: >-
                    If set, overrides the server's tool_call_sound_behavior
                    setting for this tool
                execution_mode:
                  $ref: '#/components/schemas/type_:ToolExecutionMode'
                  description: >-
                    If set, overrides the server's execution_mode setting for
                    this tool
                assignments:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:DynamicVariableAssignment'
                  description: Dynamic variable assignments for this MCP tool
components:
  schemas:
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolConfigs.update("mcp_server_id", "tool_name", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_configs.update(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete configuration override

DELETE https://api.elevenlabs.io/v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}

Remove configuration overrides for a specific MCP tool.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/tool-configuration/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete Mcp Tool Configuration Override
  version: endpoint_conversationalAi/mcpServers/toolConfigs.delete
paths:
  /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}:
    delete:
      operationId: delete
      summary: Delete Mcp Tool Configuration Override
      description: Remove configuration overrides for a specific MCP tool.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/mcpServers
          - subpackage_conversationalAi/mcpServers/toolConfigs
      parameters:
        - name: mcp_server_id
          in: path
          description: ID of the MCP Server.
          required: true
          schema:
            type: string
        - name: tool_name
          in: path
          description: Name of the MCP tool to remove config overrides for.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:McpServerResponseModel'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:McpApprovalPolicy:
      type: string
      enum:
        - value: auto_approve_all
        - value: require_approval_all
        - value: require_approval_per_tool
    type_:McpToolApprovalPolicy:
      type: string
      enum:
        - value: auto_approved
        - value: requires_approval
    type_:McpToolApprovalHash:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        tool_hash:
          type: string
          description: SHA256 hash of the tool's parameters and description
        approval_policy:
          $ref: '#/components/schemas/type_:McpToolApprovalPolicy'
          description: The approval policy for this tool
      required:
        - tool_name
        - tool_hash
    type_:McpServerTransport:
      type: string
      enum:
        - value: SSE
        - value: STREAMABLE_HTTP
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:McpServerConfigOutputUrl:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
    type_:ConvAiUserSecretDbModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        encrypted_value:
          type: string
        nonce:
          type: string
      required:
        - id
        - name
        - encrypted_value
        - nonce
    type_:McpServerConfigOutputSecretToken:
      oneOf:
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiUserSecretDbModel'
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:McpServerConfigOutputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:McpToolConfigOverride:
      type: object
      properties:
        tool_name:
          type: string
          description: The name of the MCP tool
        force_pre_tool_speech:
          type: boolean
          description: >-
            If set, overrides the server's force_pre_tool_speech setting for
            this tool
        disable_interruptions:
          type: boolean
          description: >-
            If set, overrides the server's disable_interruptions setting for
            this tool
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: If set, overrides the server's tool_call_sound setting for this tool
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            If set, overrides the server's tool_call_sound_behavior setting for
            this tool
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: If set, overrides the server's execution_mode setting for this tool
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: Dynamic variable assignments for this MCP tool
      required:
        - tool_name
    type_:McpServerConfigOutput:
      type: object
      properties:
        approval_policy:
          $ref: '#/components/schemas/type_:McpApprovalPolicy'
        tool_approval_hashes:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolApprovalHash'
          description: >-
            List of tool approval hashes for per-tool approval when
            approval_policy is REQUIRE_APPROVAL_PER_TOOL
        transport:
          $ref: '#/components/schemas/type_:McpServerTransport'
          description: The transport type used to connect to the MCP server
        url:
          $ref: '#/components/schemas/type_:McpServerConfigOutputUrl'
          description: >-
            The URL of the MCP server, if this contains a secret please store as
            a workspace secret, otherwise store as a plain string. Must use
            https
        secret_token:
          $ref: '#/components/schemas/type_:McpServerConfigOutputSecretToken'
          description: >-
            The secret token (Authorization header) stored as a workspace secret
            or in-place secret
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:McpServerConfigOutputRequestHeadersValue
          description: The headers included in the request
        name:
          type: string
        description:
          type: string
          default: ''
        force_pre_tool_speech:
          type: boolean
          default: false
          description: >-
            If true, all tools from this MCP server will require pre-tool
            execution speech
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while any
            tool from this MCP server is running.
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution for
            all tools from this MCP server
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play for all tools from
            this MCP server
        execution_mode:
          $ref: '#/components/schemas/type_:ToolExecutionMode'
          description: >-
            Determines when and how all tools from this MCP server execute:
            'immediate' executes the tool right away when requested by the LLM,
            'post_tool_speech' waits for the agent to finish speaking before
            executing, 'async' runs the tool in the background without blocking
            - best for long-running operations.
        tool_config_overrides:
          type: array
          items:
            $ref: '#/components/schemas/type_:McpToolConfigOverride'
          description: >-
            List of per-tool configuration overrides that override the
            server-level defaults for specific tools
        disable_compression:
          type: boolean
          default: false
          description: >-
            Whether to disable HTTP compression for this MCP server. Enable this
            if the server does not support compressed responses.
      required:
        - url
        - name
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:DependentAvailableAgentIdentifierAccessLevel:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:McpServerResponseModelDependentAgentsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - available
              description: 'Discriminator value: available'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
            id:
              type: string
            name:
              type: string
            created_at_unix_secs:
              type: integer
            access_level:
              $ref: >-
                #/components/schemas/type_:DependentAvailableAgentIdentifierAccessLevel
          required:
            - type
            - id
            - name
            - created_at_unix_secs
            - access_level
        - type: object
          properties:
            type:
              type: string
              enum:
                - unknown
              description: 'Discriminator value: unknown'
            referenced_resource_ids:
              type: array
              items:
                type: string
              description: >-
                If the agent is a transitive dependent, contains IDs of the
                resources that the agent depends on directly.
          required:
            - type
      discriminator:
        propertyName: type
    type_:McpServerMetadataResponseModel:
      type: object
      properties:
        created_at:
          type: integer
        owner_user_id:
          type: string
      required:
        - created_at
    type_:McpServerResponseModel:
      type: object
      properties:
        id:
          type: string
        config:
          $ref: '#/components/schemas/type_:McpServerConfigOutput'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: The access information of the MCP Server
        dependent_agents:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:McpServerResponseModelDependentAgentsItem
          description: List of agents that depend on this MCP Server.
        metadata:
          $ref: '#/components/schemas/type_:McpServerMetadataResponseModel'
          description: The metadata of the MCP Server
      required:
        - id
        - config
        - metadata

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.mcpServers.toolConfigs.delete("mcp_server_id", "tool_name");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.mcp_servers.tool_configs.delete(
    mcp_server_id="mcp_server_id",
    tool_name="tool_name"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/mcp-servers/mcp_server_id/tool-configs/tool_name")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get live count

GET https://api.elevenlabs.io/v1/convai/analytics/live-count

Get the live count of the ongoing conversations.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/analytics/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Live Count
  version: endpoint_conversationalAi/analytics/liveCount.get
paths:
  /v1/convai/analytics/live-count:
    get:
      operationId: get
      summary: Get Live Count
      description: Get the live count of the ongoing conversations.
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/analytics
          - subpackage_conversationalAi/analytics/liveCount
      parameters:
        - name: agent_id
          in: query
          description: The id of an agent to restrict the analytics to.
          required: false
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:GetLiveCountResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:GetLiveCountResponse:
      type: object
      properties:
        count:
          type: integer
          description: The number of active ongoing conversations.
      required:
        - count

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.analytics.liveCount.get({
        agentId: "agent_id",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.analytics.live_count.get(
    agent_id="agent_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/analytics/live-count?agent_id=agent_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# HIPAA

> Learn how ElevenLabs Agents, coupled with Zero Retention Mode, is designed to promote HIPAA compliance for healthcare applications. Please refer to our [compliance page](https://compliance.elevenlabs.io/) for the latest information.

## Overview

ElevenLabs Agents is one of ElevenLabs' HIPAA-eligible services, and we offer Business Associate Agreements (BAAs) to eligible customers. To the extent Covered Entities and Business Associates, as defined under HIPAA, have executed a BAA and have Zero Retention Mode engaged, ElevenLabs allows such customers to develop AI-powered voice agents for the handling Protected Health Information (PHI). The application of Zero Retention Mode is designed to promote compliance with HIPAA by limiting the processing of such PHI. You can read more about [Zero Retention Mode here](/docs/developers/resources/zero-retention-mode).

## Controls designed to promote HIPAA compliance

When HIPAA compliance is required for a workspace, and to the extent a BAA has been executed with ElevenLabs, the following policies are enabled:

1. **Zero Retention Mode** - You can read more about [Zero Retention Mode here](/docs/developers/resources/zero-retention-mode)
2. **LLM Provider Restrictions** - Only LLM from providers with whom we have a BAA in place are available as preconfigured options
3. **Storage Limitations** - Raw audio files and transcripts containing PHI are not retained

<Note>
  If you want to use LLMs that aren't available preconfigured in Zero Retention Mode, you can still use them in ElevenAgents by:

  1. Arranging to sign a BAA directly with the LLM provider you'd like to use
  2. Using your API key with our Custom LLM integration
</Note>

To the extent Zero Retention Mode is engaged, ElevenLabs' platform is designed to ensure that PHI shared as part of a conversation is not stored or logged in any system component, including:

* Conversation transcripts
* Audio recordings
* Tool calls and results
* Data analytics
* System logs

<Warning>
  For ElevenAgents, your BAA applies only to the extent provided therein. To the extent you wish to
  forego Zero Retention Mode with respect to any ElevenLabs agent, no PHI should be submitted to the
  Service in connection therewith, and such agent is no longer deemed a covered service for purposes
  of the BAA. Notwithstanding anything to the contrary, while ElevenLabs' ElevenAgents Service,
  coupled with Zero Retention Mode, is designed to promote compliance with HIPAA, you are fully
  responsible for ensuring compliance with all obligations applicable to you and for ensuring your
  use of the Services is compliant with all applicable laws.
</Warning>

## Enterprise customers

<Note>
  Execution of a BAA, as may be required by HIPAA, is only available for Enterprise tier
  subscriptions. Contact your account representative to discuss further. PHI should not be submitted
  to the ElevenLabs Services unless a BAA is in place and only to the extent permitted under such
  BAA.
</Note>

## Available LLMs

When operating in Zero Retention Mode, only the following LLMs are available:

<AccordionGroup>
  <Accordion title="Google Models">
    * Gemini 2.5 Flash
    * Gemini 2.5 Flash Lite
    * Gemini 2.0 Flash
    * Gemini 2.0 Flash Lite
    * Gemini 1.5 Flash
    * Gemini 1.5 Pro
    * Gemini 1.0 Pro
  </Accordion>

  <Accordion title="Anthropic Models">
    * Claude 3.7 Sonnet
    * Claude 3.5 Sonnet
    * Claude 3.0 Haiku
  </Accordion>

  <Accordion title="Custom LLMs">
    * [Custom LLM](/docs/agents-platform/customization/llm/custom-llm) (supports any OpenAI-API
      compatible provider and requires you to bring your own API keys)
  </Accordion>
</AccordionGroup>

## Technical implementation

Zero Retention Mode implements several safeguards and is designed to:

1. **LLM Allowlist** - Prevent use of LLMs except as provided above
2. **PII Redaction** - Automatically redact sensitive fields before storage
3. **Storage Prevention** - Disable uploading of raw audio files to cloud

## Developer experience

When working with Zero Retention Mode agents:

<Steps>
  <Step title="LLMs (except the available LLMs as described above) are disabled in the UI">
    <Frame background="subtle" caption="The UI shows disabled LLM options with tooltip explanations">
      ![Redacted conversation analysis showing Zero Retention Mode in
      action](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/01ba5fbc3d5d4a06a127f488d818428304c3f0d9500fd7931a7e4c05f8f15dab/assets/images/conversational-ai/hipaa-model.png)
    </Frame>
  </Step>

  <Step title="Content is redacted from content history">
    <Frame background="subtle" caption="All sensitive information contained within the prompt or output is redacted and not stored">
      ![Redacted conversation history showing Zero Retention Mode in
      action](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/af6abcc7d19b503a11e2daa6f9ca41eaab25be1b06417f448338ca3c4ef0b63f/assets/images/conversational-ai/redacted.png)
    </Frame>
  </Step>

  <Step title="Conversation analysis is limited">
    <Frame background="subtle" caption="Minimal information is visible to ElevenLabs given Zero Retention Mode">
      ![Redacted conversation analysis showing HIPAA compliance in
      action](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/7dd246148456ae24c454a9f55d70f730fc1183b1a0b3270c9191d259af5081bb/assets/images/conversational-ai/redacted-summary.png)
    </Frame>
  </Step>
</Steps>

### API restrictions are enforced

API calls attempting to use unavailable LLMs will receive an HTTP 400 error. Analytics data will be limited to non-sensitive metrics only.

## FAQ

<AccordionGroup>
  <Accordion title="Can I use any LLM if I am subject to HIPAA?">
    No. In such case, you can only use LLMs from the approved list. Attempts to use other LLMs will
    produce an error. You can always use a custom LLM if you need a specific model not on the
    allowlist.
  </Accordion>

  <Accordion title="Can I execute a BAA with ElevenLabs if I am subject to HIPAA?">
    BAAs are only available to enterprise customers. Please refer to your account executive to
    discuss further.
  </Accordion>

  <Accordion title="Does the application of Zero Retention Mode affect conversation quality?">
    No. Zero Retention Mode and the execution of a BAA only affects how data is stored and which
    LLMs can be used. It does not impact the quality or functionality of conversations while they
    are active.
  </Accordion>

  <Accordion title="Can I still analyze conversation data?">
    Yes, but with limitations. Conversation analytics will only include non-sensitive metadata like
    call duration and success rates. Specific content from conversations will not be available.
  </Accordion>
</AccordionGroup>

## Considerations

When building voice agents, you may consider:

1. **Use Custom LLMs** when possible, which may provide enhanced control over data processing
2. **Implement proper authentication** for all healthcare applications
3. **Validate configuration** is correct by checking redaction before launching + passing PHI

## Related resources

<CardGroup cols={2}>
  <Card title="ElevenAgents Security" href="/docs/agents-platform/customization/authentication">
    Learn about securing your ElevenLabs agents
  </Card>

  <Card title="Custom LLM Integration" href="/docs/agents-platform/customization/llm/custom-llm">
    Set up your own LLM for maximum control and compliance
  </Card>
</CardGroup>


# TCPA Compliance

> Understand key TCPA requirements for using AI agents in outbound calling

<Warning title="Legal Disclaimer">
  This guide is for informational purposes only and is not comprehensive. This guide does not
  constitute legal advice. The TCPA is complex and subject to interpretation. Consult with qualified
  legal counsel to ensure your specific use of ElevenLabs Agents for outbound calling
  complies with all applicable laws and regulations. Visit our [Compliance Portal](https://elevenlabs.io/compliance) for comprehensive information on
  our certifications and practices.
</Warning>

This guide provides a high-level overview of certain key requirements under the Telephone Consumer Protection Act (TCPA) for developers and businesses using ElevenLabs Agents for outbound calls in the United States. Adherence to the TCPA is critical when making automated calls or using AI-generated voices for outbound communications.

<Note>
  The TCPA primarily governs **outbound** calls and texts. It does not generally apply to inbound
  communications initiated by the consumer. In addition to complying with the TCPA, you must also
  comply with all applicable state-level laws that may govern telemarketing, automated calls, or the
  use of AI-generated voices. Many states have enacted their own regulations that may be more
  restrictive than federal requirements.
</Note>

## Types of Consent Required

The type of consent needed under the TCPA depends on whether your outbound call using ElevenLabs AI voice is classified as **marketing** or **non-marketing**. ElevenLabs' AI-generated voices are considered "artificial or prerecorded voices" under the TCPA, triggering specific consent rules.

| Call Type using ElevenLabs AI          | Consent Required                         | Consent Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                | Sample Consent Disclosure Language (Illustrative)                                                                                                                                                                                        |
| :------------------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Marketing Call**                     | **Prior Express Written Consent (PEWC)** | 1. A **signed written agreement** from the recipient (electronic signatures under E-SIGN Act are valid).<br /><br />2. The agreement must feature a **clear and conspicuous disclosure** stating that:<br />     (A) The recipient authorizes *\[Your Company Name]* to make automated calls using an artificial/prerecorded voice to the specific phone number provided; **AND**<br />     (B) Consent is **not** a condition of purchasing any goods or services. | "By checking this box and providing my phone number, I agree to receive automated marketing calls from \[Your Company Name], including using an AI-generated voice, at the number provided. Consent is not a condition of any purchase." |
| **Non-Marketing / Informational Call** | **Prior Express Consent (PEC)**          | The consumer must have given permission to be contacted at the number provided for informational purposes (e.g., providing a phone number for appointment reminders or account updates). While not always requiring a written agreement like PEWC, consent must still be express and affirmative.                                                                                                                                                                   | "Please provide your phone number if you'd like to receive \[e.g., appointment reminders, service updates] from *\[Your Company Name]*, including automated calls using an AI-generated voice."                                          |

<Note>
  \*Signatures for PEWC can comply with the E-SIGN Act (e.g., via website form submission, email
  confirmation, or a recorded telephone keypress after clear disclosure).
</Note>

## Key Compliance Guidelines for Developers

When using ElevenLabs Agents for outbound calling:

1. **Affirmative Opt-In**: Consent must be affirmative. Pre-checked boxes for consent are not compliant.
2. **Consent Revocation**: Consumers can revoke consent at any time through "any reasonable manner" (e.g., verbal request during a call, email, text reply like "STOP").
   * Ensure your system, especially interactive AI, can recognize and process opt-out requests, for example using our [end call tool](/docs/agents-platform/customization/tools/system-tools/end-call)
   * Honor revocations promptly, and in all cases within 10 business days..
3. **Record Keeping**: Maintain clear records of all obtained consents (who, when, where, and how consent was given) and any revocations. The burden of proving consent is on the caller.
4. **Calling Time Restrictions**: Outbound calls to residential numbers are restricted to 8:00 a.m. to 9:00 p.m. in the recipient's local time zone. Implement time-zone awareness.
5. **Do-Not-Call (DNC) Lists**:
   * Maintain an internal DNC list of individuals who have asked not to be called.
   * For marketing calls, scrub lists against the National DNC Registry, unless an exception (like valid PEWC) applies.
6. **Identify the Caller**: Clearly state the name of the company at the beginning of the call.
7. **Provide a Callback Number**: Share a toll-free number that recipients can use to opt out of future calls.
8. **Enable Automated Opt-Outs for Promotional Calls**: For promotional calls, provide an automated opt-out mechanism within two seconds of identifying the company. Include brief instructions on how to use it. If the recipient opts out, the system must (i) immediately end the call and (ii) record the number on the company's internal opt-out list. If leaving a voicemail, include a toll-free number that connects to an automated opt-out system with the same functionality.

## Understanding "Marketing"

Under the TCPA, a call is generally considered **"marketing"** if its purpose is to:

* Encourage the purchase or rental of, or investment in, property, goods, or services.
* Advertise the commercial availability or quality of any property, goods, or services.

If your call includes any promotional content, it will likely be classified as marketing, requiring PEWC.


# Disclosure requirements

> Informing end users about your use of ElevenAgents

## Overview

Your use of ElevenLabs Agents is subject to our [ElevenAgents terms](https://elevenlabs.io/agents-terms). As outlined in those Terms, you are required to provide clear notice to your end users that:

* They are interacting with AI rather than a human
* Their conversations are being recorded and may be shared with ElevenLabs and its third-party large language model providers

## Implementation

This disclosure must be presented immediately prior to any interaction with ElevenAgents. Common implementation methods include:

* A separate screen or interstitial page
* A pop-up notice
* A persistent banner
* A verbal or pre-recorded disclosure at the start of a voice call

<Warning>
  Users must not be able to access or use the feature without first being presented with this
  notice.
</Warning>

In addition to satisfying our contractual requirements, this approach promotes transparency and builds trust by ensuring users understand the nature of the interaction.

## Sample written disclosure language

You should modify this example to reflect your specific use case while maintaining the required disclosures.

<Note title="ElevenLabs Agents">
  We use ElevenLabs Agents to help power our \[insert purposes, e.g., virtual customer service
  agents]. By clicking "Agree" and each time you interact with this AI agent, you consent to us,
  ElevenLabs, and each of our service providers (including third-party LLM providers) recording,
  viewing, storing, and sharing your communications to provide the service, improve our products and
  services, train machine learning models, and comply with applicable law.
</Note>

## Sample verbal disclosure language

Hi, I’m an AI assistant. This call may be recorded and shared with service providers for quality assurance and service improvement purposes.
For more information, please refer to our privacy policy available at: \[insert link].

## Legal disclaimer

<Warning>
  The information provided above is for general informational purposes only. Your organization is
  solely responsible for ensuring that its use of ElevenAgents complies with the [ElevenAgents
  Platform Terms](https://elevenlabs.io/agents-terms) and all applicable laws and regulations. This
  guidance does not constitute legal advice. You should consult your legal counsel regarding any
  questions about legal or regulatory compliance.
</Warning>


# 11.ai integrations

> Learn about third-party integrations and their automatic Zero Retention Mode (ZRM) requirements for data privacy and compliance.

## Overview

11.ai supports various third-party integrations to seamlessly connect with your everyday applications. Some integrations automatically enable Zero Retention Mode (ZRM) to ensure compliance with industry regulations and data privacy requirements.

<Warning>
  When any integration marked with ZRM is added to an agent, all conversation data is processed in
  Zero Retention Mode, meaning no conversation transcripts, audio recordings, or personally
  identifiable information (PII) is stored or logged by ElevenLabs.
</Warning>

## Zero Retention Mode enforcement

As soon as any integration that requires ZRM is added to an agent, the entire agent automatically operates in Zero Retention Mode. This ensures:

* No call recordings are stored
* No conversation transcripts containing PII are logged
* All data is processed only in volatile memory during the request
* Compliance with healthcare (HIPAA), financial, and other regulatory requirements

## Integrations with Zero Retention Mode

The following integrations automatically enforce Zero Retention Mode to ensure compliance with data privacy policies:

| Integration     | Description                     | ZRM | Use Case                     | Compliance Requirements                  |
| --------------- | ------------------------------- | :-: | ---------------------------- | ---------------------------------------- |
| Gmail           | Email management service        |  ✅  | Email reading, organization  | Google Workspace APIs Limited Use policy |
| Google Calendar | Calendar and scheduling service |  ✅  | Event management, scheduling | Google Workspace APIs Limited Use policy |

## Google Workspace API compliance

Google integrations require Zero Retention Mode to comply with Google's Workspace APIs data policy requirements:

* **Limited Use requirements**: User data from Workspace APIs cannot be used for foundational AI/ML model training
* **Data retention restrictions**: No permanent copies of user content are created or cached beyond permitted timeframes
* **Express permission mandate**: All content access requires explicit user consent
* **Security assessment**: CASA (Cloud Application Security Assessment) certification required for restricted API scopes

<Warning>
  Google Workspace integrations are subject to additional compliance requirements and security
  assessments. Data from these integrations is processed exclusively in Zero Retention Mode with no
  storage or logging of user content.
</Warning>

<Note>
  This list is regularly updated as new integrations become available. For the most current
  information about specific integrations, please contact your ElevenLabs representative.
</Note>


# Agent tools deprecation

> Migrate from legacy `prompt.tools` to the new `prompt.tool_ids` field.

## Overview

<Info>
  The way you wire tools into your ConvAI agents is getting a refresh.
</Info>

### What's changing?

* The old request field `body.conversation_config.agent.prompt.tools` is **deprecated**.
* Use `body.conversation_config.agent.prompt.tool_ids` to list the IDs of the client or server tools your agent should use.
* **New field** `prompt.built_in_tools` is introduced for **system tools** (e.g., `end_call`, `language_detection`). These tools are referenced by **name**, not by ID.

### Critical deadlines

<Check>
  **July 14, 2025** - Last day for full backwards compatibility. You can continue using
  `prompt.tools` until this date.
</Check>

<Note>
  **July 15, 2025** - GET endpoints will stop returning the `tools` field. Only `prompt.tool_ids`
  will be included in responses.
</Note>

<Warning>
  **July 23, 2025** - Legacy `prompt.tools` field will be permanently removed. All requests
  containing this field will be rejected.
</Warning>

## Why the change?

Decoupling tools from agents brings several advantages:

* **Re-use** – the same tool can be shared across multiple agents.
* **Simpler audits** – inspect, update or delete a tool in one place.
* **Cleaner payloads** – agent configurations stay lightweight.

## What has already happened?

<Check>
  Good news — we've already migrated your data! Every tool that previously lived in `prompt.tools`
  now exists as a standalone record, and its ID is present in the agent's `prompt.tool_ids` array.
  No scripts required.
</Check>

We have **automatically migrated all existing data**:

* Every tool that was previously in an agent's `prompt.tools` array now exists as a standalone record.
* The agent's `prompt.tool_ids` array already references those new tool records.

No one-off scripts are required — your agents continue to work unchanged.

## Deprecation timeline

| Date              | Status                   | Behaviour                                                                        |
| ----------------- | ------------------------ | -------------------------------------------------------------------------------- |
| **July 14, 2025** | ✅ Full compatibility     | You may keep sending `prompt.tools`. GET responses include the `tools` field.    |
| **July 15, 2025** | ⚠️ Partial compatibility | GET endpoints stop returning the `tools` field. Only `prompt.tool_ids` included. |
| **July 23, 2025** | ❌ No compatibility       | POST and PATCH endpoints **reject** any request containing `prompt.tools`.       |

## Toolbox endpoint

All tool management lives under a dedicated endpoint:

```http title="Tool management"
POST | GET | PATCH | DELETE  https://api.elevenlabs.io/v1/convai/tools
```

Use it to:

* **Create** a tool and obtain its ID.
* **Update** it when requirements change.
* **Delete** it when it is no longer needed.

Anything that once sat in the old `tools` array now belongs here.

## Migration guide

<Error>
  System tools are **not** supported in `prompt.tool_ids`. Instead, specify them in the **new**
  `prompt.built_in_tools` field.
</Error>

If you are still using the legacy field, follow the steps below.

<Steps>
  ### 1. Stop sending `prompt.tools`

  Remove the `tools` array from your agent configuration.

  ### 2. Send the tool IDs instead

  Replace it with `prompt.tool_ids`, containing the IDs of the client or server tools the agent
  should use.

  ### 3. (Optional) Clean up

  After 23 July, delete any unused standalone tools via the toolbox endpoint.
</Steps>

## Example payloads

<Note>
  A request must include **either** `prompt.tool_ids` **or** the legacy `prompt.tools` array —
  **never both**. Sending both fields results in an error.
</Note>

<CodeBlocks>
  ```json title="Legacy format (deprecated)"
  {
    "conversation_config": {
      "agent": {
        "prompt": {
          "tools": [
            {
              "type": "client", 
              "name": "open_url",
              "description": "Open a provided URL in the user's browser."
            },
            {
              "type": "system",
              "name": "end_call", 
              "description": "",
              "response_timeout_secs": 20,
              "params": {
                "system_tool_type": "end_call"
              }
            }
          ]
        }
      }
    }
  }
  ```

  ```json title="New format (recommended) – client tool via ID + system tool"
  {
    "conversation_config": {
      "agent": {
        "prompt": {
          "tool_ids": ["tool_123456789abcdef0"],
          "built_in_tools": {
            "end_call": {
              "name": "end_call",
              "description": "",
              "response_timeout_secs": 20,
              "type": "system",
              "params": {
                "system_tool_type": "end_call"
              }
            },
            "language_detection": null,
            "transfer_to_agent": null,
            "transfer_to_number": null,
            "skip_turn": null
          }
        }
      }
    }
  }
  ```
</CodeBlocks>

## FAQ

<AccordionGroup>
  <Accordion title="Will my existing integrations break?">
    No. Until July 23, the API will silently migrate any `prompt.tools` array you send. However,
    starting July 15, GET and PATCH responses will no longer include full tool objects. After July
    23, any POST/PATCH requests containing `prompt.tools` will be rejected.
  </Accordion>

  <Accordion title="Can I mix both fields in one request?">
    No. A request must use **either** `prompt.tool_ids` **or** `prompt.tools` — never both.
  </Accordion>

  <Accordion title="How do I find a tool's ID?">
    List your tools via `GET /v1/convai/tools` or inspect the response when you create one.
  </Accordion>
</AccordionGroup>


# ElevenAPI quickstart

> Learn how to make your first ElevenLabs API request.

The ElevenLabs API provides a simple interface to state-of-the-art audio [models](/docs/overview/models) and [features](/docs/api-reference/introduction). Follow this guide to learn how to create lifelike speech with our Text to Speech API. See the [developer guides](/docs/developers/quickstart#explore-our-developer-guides) for more examples with our other products.

## Using the Text to Speech API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make your first request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    {/* This snippet was auto-generated */}

    <CodeBlocks>
      ```python
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import os

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio = elevenlabs.text_to_speech.convert(
          text="The first move is what sets everything in motion.",
          voice_id="JBFqnCBsd6RMkjVDRZzb",
          model_id="eleven_multilingual_v2",
          output_format="mp3_44100_128",
      )

      play(audio)

      ```

      ```typescript
      import { ElevenLabsClient, play } from '@elevenlabs/elevenlabs-js';
      import { Readable } from 'stream';
      import 'dotenv/config';

      const elevenlabs = new ElevenLabsClient();
      const audio = await elevenlabs.textToSpeech.convert('JBFqnCBsd6RMkjVDRZzb', {
        text: 'The first move is what sets everything in motion.',
        modelId: 'eleven_multilingual_v2',
        outputFormat: 'mp3_44100_128',
      });

      const reader = audio.getReader();
      const stream = new Readable({
        async read() {
          const { done, value } = await reader.read();
          if (done) {
            this.push(null);
          } else {
            this.push(value);
          }
        },
      });

      await play(stream);

      ```
    </CodeBlocks>
  </Step>

  <Step title="Run the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the audio play through your speakers.
  </Step>
</Steps>

## Explore our developer guides

Now that you've made your first ElevenLabs API request, you can explore the other products that ElevenLabs offers.

<CardGroup cols={2}>
  <Card title="Speech to Text" icon="duotone pen-clip" href="/docs/developers/guides/cookbooks/speech-to-text/quickstart">
    Convert spoken audio into text
  </Card>

  <Card title="Music" icon="duotone music" href="/docs/developers/guides/cookbooks/music/quickstart">
    Generate studio-quality music
  </Card>

  <Card title="Text to Dialogue" icon="duotone comment-dots" href="/docs/developers/guides/cookbooks/text-to-dialogue">
    Create natural-sounding dialogue from text
  </Card>

  <Card title="Voice Changer" icon="duotone message-pen" href="/docs/developers/guides/cookbooks/voice-changer">
    Transform the voice of an audio file
  </Card>

  <Card title="Voice Isolator" icon="duotone ear" href="/docs/developers/guides/cookbooks/voice-isolator">
    Isolate background noise from audio
  </Card>

  <Card title="Dubbing" icon="duotone language" href="/docs/developers/guides/cookbooks/dubbing">
    Dub audio/video from one language to another
  </Card>

  <Card title="Sound Effects" icon="duotone explosion" href="/docs/developers/guides/cookbooks/sound-effects">
    Generate sound effects from text
  </Card>

  <Card title="Voice Cloning" icon="duotone clone" href="/docs/developers/guides/cookbooks/voices/instant-voice-cloning">
    Clone a voice
  </Card>

  <Card title="Voice Remixing" icon="duotone shuffle" href="/docs/developers/guides/cookbooks/voices/remix-a-voice">
    Remix a voice
  </Card>

  <Card title="Voice Design" icon="duotone paint-brush" href="/docs/developers/guides/cookbooks/voices/voice-design">
    Generate voices from a single text prompt
  </Card>

  <Card title="Forced Alignment" icon="duotone objects-align-left" href="/docs/developers/guides/cookbooks/forced-alignment">
    Generate time-aligned transcripts for audio
  </Card>

  <Card title="ElevenLabs Agents" icon="duotone comments" href="/docs/agents-platform/quickstart">
    Deploy conversational voice agents
  </Card>
</CardGroup>


# Streaming text to speech

> Learn how to stream text into speech in Python or Node.js.

In this tutorial, you'll learn how to convert [text to speech](https://elevenlabs.io/text-to-speech) with the ElevenLabs SDK. We’ll start by talking through how to generate speech and receive a file and then how to generate speech and stream the response back. Finally, as a bonus we’ll show you how to upload the generated audio to an AWS S3 bucket, and share it through a signed URL. This signed URL will provide temporary access to the audio file, making it perfect for sharing with users by SMS or embedding into an application.

If you want to jump straight to an example you can find them in the [Python](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/python) and [Node.js](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/node) example repositories.

## Requirements

* An ElevenLabs account with an API key (here's how to [find your API key](/docs/developers/quickstart#authentication)).
* Python or Node installed on your machine
* (Optionally) an AWS account with access to S3.

## Setup

### Installing our SDK

Before you begin, make sure you have installed the necessary SDKs and libraries. You will need the ElevenLabs SDK for the text to speech conversion. You can install it using pip:

<CodeGroup>
  ```bash Python
  pip install elevenlabs
  ```

  ```bash TypeScript
  npm install @elevenlabs/elevenlabs-js
  ```
</CodeGroup>

Additionally, install necessary packages to manage your environmental variables:

<CodeGroup>
  ```bash Python
  pip install python-dotenv
  ```

  ```bash TypeScript
  npm install dotenv
  npm install @types/dotenv --save-dev
  ```
</CodeGroup>

Next, create a `.env` file in your project directory and fill it with your credentials like so:

```bash .env
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
```

## Convert text to speech (file)

To convert text to speech and save it as a file, we’ll use the `convert` method of the ElevenLabs SDK and then it locally as a `.mp3` file.

<CodeGroup>
  ```python Python

  import os
  import uuid
  from dotenv import load_dotenv
  from elevenlabs import VoiceSettings
  from elevenlabs.client import ElevenLabs

  load_dotenv()

  ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
  elevenlabs = ElevenLabs(
      api_key=ELEVENLABS_API_KEY,
  )


  def text_to_speech_file(text: str) -> str:
      # Calling the text_to_speech conversion API with detailed parameters
      response = elevenlabs.text_to_speech.convert(
          voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
          output_format="mp3_22050_32",
          text=text,
          model_id="eleven_turbo_v2_5", # use the turbo model for low latency
          # Optional voice settings that allow you to customize the output
          voice_settings=VoiceSettings(
              stability=0.0,
              similarity_boost=1.0,
              style=0.0,
              use_speaker_boost=True,
              speed=1.0,
          ),
      )

      # uncomment the line below to play the audio back
      # play(response)

      # Generating a unique file name for the output MP3 file
      save_file_path = f"{uuid.uuid4()}.mp3"

      # Writing the audio to a file
      with open(save_file_path, "wb") as f:
          for chunk in response:
              if chunk:
                  f.write(chunk)

      print(f"{save_file_path}: A new audio file was saved successfully!")

      # Return the path of the saved audio file
      return save_file_path

  ```

  ```typescript TypeScript
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
  import * as dotenv from 'dotenv';
  import { createWriteStream } from 'fs';
  import { v4 as uuid } from 'uuid';

  dotenv.config();

  const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

  const elevenlabs = new ElevenLabsClient({
    apiKey: ELEVENLABS_API_KEY,
  });

  export const createAudioFileFromText = async (text: string): Promise<string> => {
    return new Promise<string>(async (resolve, reject) => {
      try {
        const audio = await elevenlabs.textToSpeech.convert('JBFqnCBsd6RMkjVDRZzb', {
          modelId: 'eleven_multilingual_v2',
          text,
          outputFormat: 'mp3_44100_128',
          // Optional voice settings that allow you to customize the output
          voiceSettings: {
            stability: 0,
            similarityBoost: 0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        });

        const fileName = `${uuid()}.mp3`;
        const fileStream = createWriteStream(fileName);

        audio.pipe(fileStream);
        fileStream.on('finish', () => resolve(fileName)); // Resolve with the fileName
        fileStream.on('error', reject);
      } catch (error) {
        reject(error);
      }
    });
  };
  ```
</CodeGroup>

You can then run this function with:

<CodeGroup>
  ```python Python
  text_to_speech_file("Hello World")
  ```

  ```typescript TypeScript
  await createAudioFileFromText('Hello World');
  ```
</CodeGroup>

## Convert text to speech (streaming)

If you prefer to stream the audio directly without saving it to a file, you can use our streaming feature.

<CodeGroup>
  ```python Python

  import os
  from typing import IO
  from io import BytesIO
  from dotenv import load_dotenv
  from elevenlabs import VoiceSettings
  from elevenlabs.client import ElevenLabs

  load_dotenv()

  ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
  elevenlabs = ElevenLabs(
      api_key=ELEVENLABS_API_KEY,
  )


  def text_to_speech_stream(text: str) -> IO[bytes]:
      # Perform the text-to-speech conversion
      response = elevenlabs.text_to_speech.stream(
          voice_id="pNInz6obpgDQGcFmaJgB", # Adam pre-made voice
          output_format="mp3_22050_32",
          text=text,
          model_id="eleven_multilingual_v2",
          # Optional voice settings that allow you to customize the output
          voice_settings=VoiceSettings(
              stability=0.0,
              similarity_boost=1.0,
              style=0.0,
              use_speaker_boost=True,
              speed=1.0,
          ),
      )

      # Create a BytesIO object to hold the audio data in memory
      audio_stream = BytesIO()

      # Write each chunk of audio data to the stream
      for chunk in response:
          if chunk:
              audio_stream.write(chunk)

      # Reset stream position to the beginning
      audio_stream.seek(0)

      # Return the stream for further use
      return audio_stream

  ```

  ```typescript TypeScript
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
  import * as dotenv from 'dotenv';

  dotenv.config();

  const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

  if (!ELEVENLABS_API_KEY) {
    throw new Error('Missing ELEVENLABS_API_KEY in environment variables');
  }

  const elevenlabs = new ElevenLabsClient({
    apiKey: ELEVENLABS_API_KEY,
  });

  export const createAudioStreamFromText = async (text: string): Promise<Buffer> => {
    const audioStream = await elevenlabs.textToSpeech.stream('JBFqnCBsd6RMkjVDRZzb', {
      modelId: 'eleven_multilingual_v2',
      text,
      outputFormat: 'mp3_44100_128',
      // Optional voice settings that allow you to customize the output
      voiceSettings: {
        stability: 0,
        similarityBoost: 1.0,
        useSpeakerBoost: true,
        speed: 1.0,
      },
    });

    const chunks: Buffer[] = [];
    for await (const chunk of audioStream) {
      chunks.push(chunk);
    }

    const content = Buffer.concat(chunks);
    return content;
  };
  ```
</CodeGroup>

You can then run this function with:

<CodeGroup>
  ```python Python
  text_to_speech_stream("This is James")
  ```

  ```typescript TypeScript
  await createAudioStreamFromText('This is James');
  ```
</CodeGroup>

## Bonus - Uploading to AWS S3 and getting a secure sharing link

Once your audio data is created as either a file or a stream you might want to share this with your users. One way to do this is to upload it to an AWS S3 bucket and generate a secure sharing link.

<AccordionGroup>
  <Accordion title="Creating your AWS credentials">
    To upload the data to S3 you’ll need to add your AWS access key ID, secret access key and AWS region name to your `.env` file. Follow these steps to find the credentials:

    1. Log in to your AWS Management Console: Navigate to the AWS home page and sign in with your account.

    <Frame caption="AWS Console Login">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/e9f1f1b1950962c3d67ea25a0593ca989d33c9f49b641e22eb3f861fc72735e3/assets/images/cookbooks/aws_console_login.webp" />
    </Frame>

    2. Access the IAM (Identity and Access Management) Dashboard: You can find IAM under "Security, Identity, & Compliance" on the services menu. The IAM dashboard manages access to your AWS services securely.

    <Frame caption="AWS IAM Dashboard">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d6fa7e75879e7537693c4edde16d0ac5face78d72b00de50743a754c0681a5e3/assets/images/cookbooks/aws_iam_dashboard.webp" />
    </Frame>

    3. Create a New User (if necessary): On the IAM dashboard, select "Users" and then "Add user". Enter a user name.

    <Frame caption="Add AWS IAM User">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/47b05ffda6925e4e14147aadc296d7c86cbd3340aaa1025083f1e1464b230f51/assets/images/cookbooks/aws_iam_add_user.webp" />
    </Frame>

    4. Set the permissions: attach policies directly to the user according to the access level you wish to grant. For S3 uploads, you can use the AmazonS3FullAccess policy. However, it's best practice to grant least privilege, or the minimal permissions necessary to perform a task. You might want to create a custom policy that specifically allows only the necessary actions on your S3 bucket.

    <Frame caption="Set Permission for AWS IAM User">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/4b88bba4f5bb1509aa087a1ab5cc8068a274b17d8887c563f050b77e8438bb94/assets/images/cookbooks/aws_iam_set_permission.webp" />
    </Frame>

    5. Review and create the user: Review your settings and create the user. Upon creation, you'll be presented with an access key ID and a secret access key. Be sure to download and securely save these credentials; the secret access key cannot be retrieved again after this step.

    <Frame caption="AWS Access Secret Key">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/27dcdff3681522cf936ff6bfb81cf216ada1fe401c7c1dbd10e58cead8a48abc/assets/images/cookbooks/aws_access_secret_key.webp" />
    </Frame>

    6. Get AWS region name: ex. us-east-1

    <Frame caption="AWS Region Name">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/016bc11c2f040942b215366c5fc9ac8e01f6261f5ebd44a3456d4b7ba97e9ae8/assets/images/cookbooks/aws_region_name.webp" />
    </Frame>

    If you do not have an AWS S3 bucket, you will need to create a new one by following these steps:

    1. Access the S3 dashboard: You can find S3 under "Storage" on the services menu.

    <Frame caption="AWS S3 Dashboard">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d2455fa92ce6dfa705c3b91144fe22539fae1611848cb8e3cc2dac20e57db4e7/assets/images/cookbooks/aws_s3_dashboard.webp" />
    </Frame>

    2. Create a new bucket: On the S3 dashboard, click the "Create bucket" button.

    <Frame caption="Click Create Bucket Button">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/3b7d5bdb6559e8511445b41b1bbdeed3f6674791cf23021a30ccb5aa8143be28/assets/images/cookbooks/aws_s3_create_bucket.webp" />
    </Frame>

    3. Enter a bucket name and click on the "Create bucket" button. You can leave the other bucket options as default. The newly added bucket will appear in the list.

    <Frame caption="Enter a New S3 Bucket Name">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/68d23f21bec1e3aa70b18f09c40c9bdace5ff0dd63edc17c6807e7ddac75758d/assets/images/cookbooks/aws_s3_enter_bucket_name.webp" />
    </Frame>

    <Frame caption="S3 Bucket List">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/63f7af93d4a73fab3011853c8393c954400d9f344a5811ec90b86d6c69b2ec16/assets/images/cookbooks/aws_s3_bucket_list.webp" />
    </Frame>
  </Accordion>

  <Accordion title="Installing the AWS SDK and adding the credentials">
    Install `boto3` for interacting with AWS services using `pip` and `npm`.

    <CodeGroup>
      ```bash Python
      pip install boto3
      ```

      ```bash TypeScript
      npm install @aws-sdk/client-s3
      npm install @aws-sdk/s3-request-presigner
      ```
    </CodeGroup>

    Then add the environment variables to `.env` file like so:

    ```
    AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
    AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
    AWS_REGION_NAME=your_aws_region_name_here
    AWS_S3_BUCKET_NAME=your_s3_bucket_name_here
    ```
  </Accordion>

  <Accordion title="Uploading to AWS S3 and generating the signed URL">
    Add the following functions to upload the audio stream to S3 and generate a signed URL.

    <CodeGroup>
      ```python s3_uploader.py (Python)

      import os
      import boto3
      import uuid

      AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
      AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
      AWS_REGION_NAME = os.getenv("AWS_REGION_NAME")
      AWS_S3_BUCKET_NAME = os.getenv("AWS_S3_BUCKET_NAME")

      session = boto3.Session(
          aws_access_key_id=AWS_ACCESS_KEY_ID,
          aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
          region_name=AWS_REGION_NAME,
      )
      s3 = session.client("s3")


      def generate_presigned_url(s3_file_name: str) -> str:
          signed_url = s3.generate_presigned_url(
              "get_object",
              Params={"Bucket": AWS_S3_BUCKET_NAME, "Key": s3_file_name},
              ExpiresIn=3600,
          )  # URL expires in 1 hour
          return signed_url


      def upload_audiostream_to_s3(audio_stream) -> str:
          s3_file_name = f"{uuid.uuid4()}.mp3"  # Generates a unique file name using UUID
          s3.upload_fileobj(audio_stream, AWS_S3_BUCKET_NAME, s3_file_name)

          return s3_file_name

      ```

      ```typescript s3_uploader.ts (TypeScript)
      import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
      import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
      import * as dotenv from 'dotenv';
      import { v4 as uuid } from 'uuid';

      dotenv.config();

      const { AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME, AWS_S3_BUCKET_NAME } =
        process.env;

      if (!AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_REGION_NAME || !AWS_S3_BUCKET_NAME) {
        throw new Error('One or more environment variables are not set. Please check your .env file.');
      }

      const s3 = new S3Client({
        credentials: {
          accessKeyId: AWS_ACCESS_KEY_ID,
          secretAccessKey: AWS_SECRET_ACCESS_KEY,
        },
        region: AWS_REGION_NAME,
      });

      export const generatePresignedUrl = async (objectKey: string) => {
        const getObjectParams = {
          Bucket: AWS_S3_BUCKET_NAME,
          Key: objectKey,
          Expires: 3600,
        };
        const command = new GetObjectCommand(getObjectParams);
        const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
        return url;
      };

      export const uploadAudioStreamToS3 = async (audioStream: Buffer) => {
        const remotePath = `${uuid()}.mp3`;
        await s3.send(
          new PutObjectCommand({
            Bucket: AWS_S3_BUCKET_NAME,
            Key: remotePath,
            Body: audioStream,
            ContentType: 'audio/mpeg',
          })
        );
        return remotePath;
      };
      ```
    </CodeGroup>

    You can then call uploading function with the audio stream from the text.

    <CodeGroup>
      ```python Python
      s3_file_name = upload_audiostream_to_s3(audio_stream)
      ```

      ```typescript TypeScript
      const s3path = await uploadAudioStreamToS3(stream);
      ```
    </CodeGroup>

    After uploading the audio file to S3, generate a signed URL to share access to the file. This URL will be time-limited, meaning it will expire after a certain period, making it secure for temporary sharing.

    You can now generate a URL from a file with:

    <CodeGroup>
      ```python Python
      signed_url = generate_presigned_url(s3_file_name)
      print(f"Signed URL to access the file: {signed_url}")
      ```

      ```typescript TypeScript
      const presignedUrl = await generatePresignedUrl(s3path);
      console.log('Presigned URL:', presignedUrl);
      ```
    </CodeGroup>

    If you want to use the file multiple times, you should store the s3 file path in your database and then regenerate the signed URL each time you need rather than saving the signed URL directly as it will expire.
  </Accordion>

  <Accordion title="Putting it all together">
    To put it all together, you can use the following script:

    <CodeGroup>
      ```python main.py (Python)

      import os

      from dotenv import load_dotenv

      load_dotenv()

      from text_to_speech_stream import text_to_speech_stream
      from s3_uploader import upload_audiostream_to_s3, generate_presigned_url


      def main():
          text = "This is James"

          audio_stream = text_to_speech_stream(text)
          s3_file_name = upload_audiostream_to_s3(audio_stream)
          signed_url = generate_presigned_url(s3_file_name)

          print(f"Signed URL to access the file: {signed_url}")


      if __name__ == "__main__":
          main()

      ```

      ```typescript index.ts (Typescript)
      import 'dotenv/config';

      import { generatePresignedUrl, uploadAudioStreamToS3 } from './s3_uploader';
      import { createAudioFileFromText } from './text_to_speech_file';
      import { createAudioStreamFromText } from './text_to_speech_stream';

      (async () => {
        // save the audio file to disk
        const fileName = await createAudioFileFromText(
          'Today, the sky is exceptionally clear, and the sun shines brightly.'
        );

        console.log('File name:', fileName);

        // OR stream the audio, upload to S3, and get a presigned URL
        const stream = await createAudioStreamFromText(
          'Today, the sky is exceptionally clear, and the sun shines brightly.'
        );

        const s3path = await uploadAudioStreamToS3(stream);

        const presignedUrl = await generatePresignedUrl(s3path);

        console.log('Presigned URL:', presignedUrl);
      })();
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Conclusion

You now know how to convert text into speech and generate a signed URL to share the audio file. This functionality opens up numerous opportunities for creating and sharing content dynamically.

Here are some examples of what you could build with this.

1. **Educational Podcasts**: Create personalized educational content that can be accessed by students on demand. Teachers can convert their lessons into audio format, upload them to S3, and share the links with students for a more engaging learning experience outside the traditional classroom setting.

2. **Accessibility Features for Websites**: Enhance website accessibility by offering text content in audio format. This can make information on websites more accessible to individuals with visual impairments or those who prefer auditory learning.

3. **Automated Customer Support Messages**: Produce automated and personalized audio messages for customer support, such as FAQs or order updates. This can provide a more engaging customer experience compared to traditional text emails.

4. **Audio Books and Narration**: Convert entire books or short stories into audio format, offering a new way for audiences to enjoy literature. Authors and publishers can diversify their content offerings and reach audiences who prefer listening over reading.

5. **Language Learning Tools**: Develop language learning aids that provide learners with audio lessons and exercises. This makes it possible to practice pronunciation and listening skills in a targeted way.

For more details, visit the following to see the full project files which give a clear structure for setting up your application:

For Python: [example repo](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/python)

For TypeScript: [example repo](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/node)

If you have any questions please create an issue on the [elevenlabs-doc Github](https://github.com/elevenlabs/elevenlabs-docs/issues).


# Stitching multiple requests

> Learn how to maintain voice prosody over multiple chunks/generations.

When converting a large body of text into audio, you may encounter abrupt changes in prosody from one chunk to another. This can be particularly noticeable when converting text that spans multiple paragraphs or sections. In order to maintain voice prosody over multiple chunks, you can use the Request Stitching feature.

This feature allows you to provide context on what has already been generated and what will be generated in the future, helping to maintain a consistent voice and prosody throughout the entire text.

<Info>
  Request stitching is not available for the 

  `eleven_v3`

   model.
</Info>

Here's an example without Request Stitching:

<video controls src="https://eleven-public-cdn.elevenlabs.io/audio/docs/without_request_stitching.mp3" />

And the same example with Request Stitching:

<video controls src="https://eleven-public-cdn.elevenlabs.io/audio/docs/with_request_stitching.mp3" />

## How to use Request Stitching

Request Stitching is easiest when using the ElevenLabs SDKs.

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Stitch multiple requests together">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python
      import os
      from io import BytesIO
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      from dotenv import load_dotenv

      load_dotenv()

      ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")

      elevenlabs = ElevenLabs(
          api_key=ELEVENLABS_API_KEY,
      )

      paragraphs = [
          "The advent of technology has transformed countless sectors, with education ",
          "standing out as one of the most significantly impacted fields.",
          "In recent years, educational technology, or EdTech, has revolutionized the way ",
          "teachers deliver instruction and students absorb information.",
          "From interactive whiteboards to individual tablets loaded with educational software, ",
          "technology has opened up new avenues for learning that were previously unimaginable.",
          "One of the primary benefits of technology in education is the accessibility it provides.",
      ]

      request_ids = []
      audio_buffers = []

      for paragraph in paragraphs:
          # Usually we get back a stream from the convert function, but with_raw_response is
          # used to get the headers from the response
          with elevenlabs.text_to_speech.with_raw_response.convert(
              text=paragraph,
              voice_id="T7QGPtToiqH4S8VlIkMJ",
              model_id="eleven_multilingual_v2",
              previous_request_ids=request_ids
          ) as response:
              request_ids.append(response._response.headers.get("request-id"))

              # response._response.headers also contains useful information like 'character-cost',
              # which shows the cost of the generation in characters.

              audio_data = b''.join(chunk for chunk in response.data)
              audio_buffers.append(BytesIO(audio_data))

      combined_stream = BytesIO(b''.join(buffer.getvalue() for buffer in audio_buffers))

      play(combined_stream)
      ```

      ```typescript
      import "dotenv/config";
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import { Readable } from "node:stream";

      const elevenlabs = new ElevenLabsClient({
          apiKey: process.env.ELEVENLABS_API_KEY,
      });

      const paragraphs = [
          "The advent of technology has transformed countless sectors, with education ",
          "standing out as one of the most significantly impacted fields.",
          "In recent years, educational technology, or EdTech, has revolutionized the way ",
          "teachers deliver instruction and students absorb information.",
          "From interactive whiteboards to individual tablets loaded with educational software, ",
          "technology has opened up new avenues for learning that were previously unimaginable.",
          "One of the primary benefits of technology in education is the accessibility it provides.",
      ];

      const requestIds: string[] = [];
      const audioBuffers: Buffer[] = [];

      for (const paragraph of paragraphs) {
          // Usually we get back a stream from the convert function, but withRawResponse() is
          // used to get the headers from the response
          const response = await elevenlabs.textToSpeech
              .convert("T7QGPtToiqH4S8VlIkMJ", {
                  text: paragraph,
                  modelId: "eleven_multilingual_v2",
                  previousRequestIds: requestIds,
              })
              .withRawResponse();

          // response.rawResponse.headers also contains useful information like 'character-cost',
          // which shows the cost of the generation in characters.

          requestIds.push(response.rawResponse.headers.get("request-id") ?? "");

          // Convert stream to buffer
          const chunks: Buffer[] = [];
          for await (const chunk of response.data) {
              chunks.push(Buffer.from(chunk));
          }
          audioBuffers.push(Buffer.concat(chunks));
      }

      // Create a single readable stream from all buffers
      const combinedStream = Readable.from(Buffer.concat(audioBuffers));

      play(combinedStream);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the combined stitched audio play.
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="How does Request Stitching work with streaming?">
    In order to use the request IDs of a previous request for conditioning it needs to have processed completely. In case of streaming this means the audio has to be read completely from the response body.
  </Accordion>

  <Accordion title="How much difference does Request Stitching make?">
    The difference depends on the model, voice and voice settings used.
  </Accordion>

  <Accordion title="How old can the request IDs be?">
    The request IDs should be no older than two hours.
  </Accordion>

  <Accordion title="Is Request Stitching available on every plan?">
    Yes, unless you are an enterprise user with increased privacy requirements.
  </Accordion>
</AccordionGroup>


# Using pronunciation dictionaries

> Learn how to manage pronunciation dictionaries programmatically.

## Overview

Pronunciation dictionaries allow you to customize how your AI agent pronounces specific words or phrases. This is particularly useful for:

* Correcting pronunciation of names, places, or technical terms
* Ensuring consistent pronunciation across conversations
* Customizing regional pronunciation variations

ElevenLabs supports both [IPA](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) and [CMU](https://en.wikipedia.org/wiki/CMU_Pronouncing_Dictionary) alphabets.

<Info>
  Phoneme tags only work with `eleven_flash_v2`, `eleven_turbo_v2` & `eleven_monolingual_v1` models.
  If you use phoneme tags with other models, they will silently skip the word.
</Info>

<Info>
  Phoneme tags (IPA/CMU) only work for English. For other languages, use Alias tags instead, which
  replace words with alternative spellings or phrases that produce the desired pronunciation.
</Info>

## Quickstart

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Create a pronunciation dictionary file">
    In this example, we will create a pronunciation dictionary file for the word `tomato`.

    This rule will use the "IPA" alphabet and update the pronunciation for `tomato` and `Tomato` with a different pronunciation. PLS files are case sensitive which is why we include it both with and without a capital "T".

    <Tip>
      You can use AI tools like Claude or ChatGPT to help generate IPA or CMU notations for specific words.
    </Tip>

    ```xml title="dictionary.pls"
    <?xml version="1.0" encoding="UTF-8"?>
    <lexicon version="1.0"
        xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.w3.org/2005/01/pronunciation-lexicon
            http://www.w3.org/TR/2007/CR-pronunciation-lexicon-20071212/pls.xsd"
        alphabet="ipa" xml:lang="en-US">
    <lexeme>
        <grapheme>tomato</grapheme>
        <phoneme>/tə'meɪtoʊ/</phoneme>
    </lexeme>
    <lexeme>
        <grapheme>Tomato</grapheme>
        <phoneme>/tə'meɪtoʊ/</phoneme>
    </lexeme>
    </lexicon>
    ```
  </Step>

  <Step title="Create a pronunciation dictionary from a file via the SDK">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      import requests
      from elevenlabs.play import play, PronunciationDictionaryVersionLocator

      with open("dictionary.pls", "rb") as f:
          # this dictionary changes how tomato is pronounced
          pronunciation_dictionary = elevenlabs.pronunciation_dictionaries.create_from_file(
              file=f.read(), name="example"
          )

      audio_1 = elevenlabs.text_to_speech.convert(
          text="Without the dictionary: tomato",
          voice_id="aMSt68OGf4xUZAnLpTU8",
          model_id="eleven_turbo_v2",
      )

      audio_2 = elevenlabs.text_to_speech.convert(
          text="With the dictionary: tomato",
          voice_id="aMSt68OGf4xUZAnLpTU8",
          model_id="eleven_turbo_v2",
          pronunciation_dictionary_locators=[
              PronunciationDictionaryVersionLocator(
                  pronunciation_dictionary_id=pronunciation_dictionary.id,
                  version_id=pronunciation_dictionary.version_id,
              )
          ],
      )

      # play the audio
      play(audio_1)
      play(audio_2)
      ```

      ```typescript maxLines=0
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      import fs from "node:fs";

      const elevenlabs = new ElevenLabsClient();

      const pronunciationDictionary = await elevenlabs.pronunciationDictionaries.createFromFile({
          file: fs.createReadStream("dictionary.pls"),
      });

      const audio1 = await elevenlabs.textToSpeech.convert("Without the dictionary: tomato", {
          voiceId: "aMSt68OGf4xUZAnLpTU8",
          modelId: "eleven_turbo_v2",
      });

      const audio2 = await elevenlabs.textToSpeech.convert("With the dictionary: tomato", {
          voiceId: "aMSt68OGf4xUZAnLpTU8",
          modelId: "eleven_turbo_v2",
          pronunciationDictionaryLocators: [
              {
                  pronunciationDictionaryId: pronunciationDictionary.id,
                  versionId: pronunciationDictionary.versionId,
              },
          ],
      });

      play(audio1);
      play(audio2);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear two versions of the audio playing through your speakers, one with and one without the pronunciation dictionary.
  </Step>
</Steps>

## Next steps

To learn more about pronunciation dictionaries, please refer to the [API reference](/docs/api-reference/pronunciation-dictionaries/create-from-file).


# Streaming and Caching with Supabase

> Generate and stream speech through Supabase Edge Functions. Store speech in Supabase Storage and cache responses via built-in CDN.

## Introduction

In this tutorial you will learn how to build and edge API to generate, stream, store, and cache speech using Supabase Edge Functions, Supabase Storage, and ElevenLabs.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/4Roog4PAmZ8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [example project on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/supabase/stream-and-cache-storage).
</Tip>

## Requirements

* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys).
* A [Supabase](https://supabase.com) account (you can sign up for a free account via [database.new](https://database.new)).
* The [Supabase CLI](https://supabase.com/docs/guides/local-development) installed on your machine.
* The [Deno runtime](https://docs.deno.com/runtime/getting_started/installation/) installed on your machine and optionally [setup in your facourite IDE](https://docs.deno.com/runtime/getting_started/setup_your_environment).

## Setup

### Create a Supabase project locally

After installing the [Supabase CLI](https://supabase.com/docs/guides/local-development), run the following command to create a new Supabase project locally:

```bash
supabase init
```

### Configure the storage bucket

You can configure the Supabase CLI to automatically generate a storage bucket by adding this configuration in the `config.toml` file:

```toml ./supabase/config.toml
[storage.buckets.audio]
public = false
file_size_limit = "50MiB"
allowed_mime_types = ["audio/mp3"]
objects_path = "./audio"
```

<Note>
  Upon running `supabase start` this will create a new storage bucket in your local Supabase
  project. Should you want to push this to your hosted Supabase project, you can run `supabase seed
    buckets --linked`.
</Note>

### Configure background tasks for Supabase Edge Functions

To use background tasks in Supabase Edge Functions when developing locally, you need to add the following configuration in the `config.toml` file:

```toml ./supabase/config.toml
[edge_runtime]
policy = "per_worker"
```

<Note>
  When running with `per_worker` policy, Function won't auto-reload on edits. You will need to
  manually restart it by running `supabase functions serve`.
</Note>

### Create a Supabase Edge Function for Speech generation

Create a new Edge Function by running the following command:

```bash
supabase functions new text-to-speech
```

If you're using VS Code or Cursor, select `y` when the CLI prompts "Generate VS Code settings for Deno? \[y/N]"!

### Set up the environment variables

Within the `supabase/functions` directory, create a new `.env` file and add the following variables:

```env supabase/functions/.env
# Find / create an API key at https://elevenlabs.io/app/settings/api-keys
ELEVENLABS_API_KEY=your_api_key
```

### Dependencies

The project uses a couple of dependencies:

* The [@supabase/supabase-js](https://supabase.com/docs/reference/javascript) library to interact with the Supabase database.
* The ElevenLabs [JavaScript SDK](/docs/developers/quickstart) to interact with the text-to-speech API.
* The open-source [object-hash](https://www.npmjs.com/package/object-hash) to generate a hash from the request parameters.

Since Supabase Edge Function uses the [Deno runtime](https://deno.land/), you don't need to install the dependencies, rather you can [import](https://docs.deno.com/examples/npm/) them via the `npm:` prefix.

## Code the Supabase Edge Function

In your newly created `supabase/functions/text-to-speech/index.ts` file, add the following code:

```ts supabase/functions/text-to-speech/index.ts
// Setup type definitions for built-in Supabase Runtime APIs
import 'jsr:@supabase/functions-js/edge-runtime.d.ts';
import { createClient } from 'jsr:@supabase/supabase-js@2';
import { ElevenLabsClient } from 'npm:elevenlabs';
import * as hash from 'npm:object-hash';

const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
);

const elevenlabs = new ElevenLabsClient({
  apiKey: Deno.env.get('ELEVENLABS_API_KEY'),
});

// Upload audio to Supabase Storage in a background task
async function uploadAudioToStorage(stream: ReadableStream, requestHash: string) {
  const { data, error } = await supabase.storage
    .from('audio')
    .upload(`${requestHash}.mp3`, stream, {
      contentType: 'audio/mp3',
    });

  console.log('Storage upload result', { data, error });
}

Deno.serve(async (req) => {
  // To secure your function for production, you can for example validate the request origin,
  // or append a user access token and validate it with Supabase Auth.
  console.log('Request origin', req.headers.get('host'));
  const url = new URL(req.url);
  const params = new URLSearchParams(url.search);
  const text = params.get('text');
  const voiceId = params.get('voiceId') ?? 'JBFqnCBsd6RMkjVDRZzb';

  const requestHash = hash.MD5({ text, voiceId });
  console.log('Request hash', requestHash);

  // Check storage for existing audio file
  const { data } = await supabase.storage.from('audio').createSignedUrl(`${requestHash}.mp3`, 60);

  if (data) {
    console.log('Audio file found in storage', data);
    const storageRes = await fetch(data.signedUrl);
    if (storageRes.ok) return storageRes;
  }

  if (!text) {
    return new Response(JSON.stringify({ error: 'Text parameter is required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  try {
    console.log('ElevenLabs API call');
    const response = await elevenlabs.textToSpeech.stream(voiceId, {
      output_format: 'mp3_44100_128',
      model_id: 'eleven_multilingual_v2',
      text,
    });

    const stream = new ReadableStream({
      async start(controller) {
        for await (const chunk of response) {
          controller.enqueue(chunk);
        }
        controller.close();
      },
    });

    // Branch stream to Supabase Storage
    const [browserStream, storageStream] = stream.tee();

    // Upload to Supabase Storage in the background
    EdgeRuntime.waitUntil(uploadAudioToStorage(storageStream, requestHash));

    // Return the streaming response immediately
    return new Response(browserStream, {
      headers: {
        'Content-Type': 'audio/mpeg',
      },
    });
  } catch (error) {
    console.log('error', { error });
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
});
```

### Code deep dive

There's a couple of things worth noting about the code. Let's step through it step by step.

<Steps>
  <Step title="Handle the incoming request">
    To handle the incoming request, use the `Deno.serve` handler. In the demo we don't validate the request origin, but you can for example validate the request origin, or append a user access token and validate it with [Supabase Auth](https://supabase.com/docs/guides/functions/auth).

    From the incoming request, the function extracts the `text` and `voiceId` parameters. The `voiceId` parameter is optional and defaults to the ElevenLabs ID for the "Allison" voice.

    Using the `object-hash` library, the function generates a hash from the request parameters. This hash is used to check for existing audio files in Supabase Storage.

    ```ts {1,5-8}
    Deno.serve(async (req) => {
    // To secure your function for production, you can for example validate the request origin,
    // or append a user access token and validate it with Supabase Auth.
    console.log("Request origin", req.headers.get("host"));
    const url = new URL(req.url);
    const params = new URLSearchParams(url.search);
    const text = params.get("text");
    const voiceId = params.get("voiceId") ?? "JBFqnCBsd6RMkjVDRZzb";

    const requestHash = hash.MD5({ text, voiceId });
    console.log("Request hash", requestHash);

    // ...
    })
    ```
  </Step>

  <Step title="Check for existing audio file in Supabase Storage">
    Supabase Storage comes with a [smart CDN built-in](https://supabase.com/docs/guides/storage/cdn/smart-cdn) allowing you to easily cache and serve your files.

    Here, the function checks for an existing audio file in Supabase Storage. If the file exists, the function returns the file from Supabase Storage.

    ```ts {4,9}
    const { data } = await supabase
      .storage
      .from("audio")
      .createSignedUrl(`${requestHash}.mp3`, 60);

    if (data) {
      console.log("Audio file found in storage", data);
      const storageRes = await fetch(data.signedUrl);
      if (storageRes.ok) return storageRes;
    }
    ```
  </Step>

  <Step title="Generate Speech as a stream and split into two branches">
    Using the streaming capabilities of the ElevenLabs API, the function generates a stream. The benefit here is that even for larger text, you can start streaming the audio back to your user immediately, and then upload the stream to Supabase Storage in the background.

    This allows for the best possible user experience, making even large text blocks feel magically quick. The magic here happens on line 17, where the `stream.tee()` method branches the readablestream into two branches: one for the browser and one for Supabase Storage.

    ```ts {1,17,20,22-27}
    try {
      const response = await elevenlabs.textToSpeech.stream(voiceId, {
        output_format: "mp3_44100_128",
        model_id: "eleven_multilingual_v2",
        text,
      });

      const stream = new ReadableStream({
        async start(controller) {
          for await (const chunk of response) {
            controller.enqueue(chunk);
          }
          controller.close();
        },
      });

      // Branch stream to Supabase Storage
      const [browserStream, storageStream] = stream.tee();

      // Upload to Supabase Storage in the background
      EdgeRuntime.waitUntil(uploadAudioToStorage(storageStream, requestHash));

      // Return the streaming response immediately
      return new Response(browserStream, {
        headers: {
          "Content-Type": "audio/mpeg",
        },
      });
    } catch (error) {
      console.log("error", { error });
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { "Content-Type": "application/json" },
      });
    }
    ```
  </Step>

  <Step title="Upload the audio stream to Supabase Storage in the background">
    The `EdgeRuntime.waitUntil` method on line 20 in the previous step is used to upload the audio stream to Supabase Storage in the background using the `uploadAudioToStorage` function. This allows the function to return the streaming response immediately to the browser, while the audio is being uploaded to Supabase Storage.

    Once the storage object has been created, the next time your users makes a request with the same parameters, the function will return the audio file from the Supabase Storage CDN.

    ```ts {2,8-10}
    // Upload audio to Supabase Storage in a background task
    async function uploadAudioToStorage(
      stream: ReadableStream,
      requestHash: string,
    ) {
      const { data, error } = await supabase.storage
        .from("audio")
        .upload(`${requestHash}.mp3`, stream, {
          contentType: "audio/mp3",
        });

      console.log("Storage upload result", { data, error });
    }
    ```
  </Step>
</Steps>

## Run locally

To run the function locally, run the following commands:

```bash
supabase start
```

Once the local Supabase stack is up and running, run the following command to start the function and observe the logs:

```bash
supabase functions serve
```

### Try it out

Navigate to `http://127.0.0.1:54321/functions/v1/text-to-speech?text=hello%20world` to hear the function in action.

Afterwards, navigate to `http://127.0.0.1:54323/project/default/storage/buckets/audio` to see the audio file in your local Supabase Storage bucket.

## Deploy to Supabase

If you haven't already, create a new Supabase account at [database.new](https://database.new) and link the local project to your Supabase account:

```bash
supabase link
```

Once done, run the following command to deploy the function:

```bash
supabase functions deploy
```

### Set the function secrets

Now that you have all your secrets set locally, you can run the following command to set the secrets in your Supabase project:

```bash
supabase secrets set --env-file supabase/functions/.env
```

## Test the function

The function is designed in a way that it can be used directly as a source for an `<audio>` element.

```html
<audio
  src="https://${SUPABASE_PROJECT_REF}.supabase.co/functions/v1/text-to-speech?text=Hello%2C%20world!&voiceId=JBFqnCBsd6RMkjVDRZzb"
  controls
/>
```

You can find an example frontend implementation in the complete code example on [GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/supabase/stream-and-cache-storage/src/pages/Index.tsx).


# Sending generated audio through Twilio

> Learn how to integrate generated speech into phone calls with Twilio.

In this guide, you’ll learn how to send an AI generated message through a phone call using Twilio and ElevenLabs. This process allows you to send high-quality voice messages directly to your callers.

## Create accounts with Twilio and ngrok

We’ll be using Twilio and ngrok for this guide, so go ahead and create accounts with them.

* [twilio.com](https://www.twilio.com)
* [ngrok.com](https://ngrok.com)

## Get the code

If you want to get started quickly, you can get the entire code for this guide on [GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/twilio/call)

## Create the server with Express

### Initialize your project

Create a new folder for your project

```
mkdir elevenlabs-twilio
cd elevenlabs-twilio
npm init -y
```

### Install dependencies

```
npm install @elevenlabs/elevenlabs-js express express-ws twilio
```

### Install dev dependencies

```
npm i @types/node @types/express @types/express-ws @types/ws dotenv tsx typescript
```

### Create your files

```ts
// src/app.ts
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express, { Response } from 'express';
import ExpressWs from 'express-ws';
import { Readable } from 'stream';
import VoiceResponse from 'twilio/lib/twiml/VoiceResponse';
import { type WebSocket } from 'ws';

const app = ExpressWs(express()).app;
const PORT: number = parseInt(process.env.PORT || '5000');

const elevenlabs = new ElevenLabsClient();
const voiceId = 'aMSt68OGf4xUZAnLpTU8';
const outputFormat = 'ulaw_8000';
const text = 'This is a test. You can now hang up. Thank you.';

function startApp() {
  app.post('/call/incoming', (_, res: Response) => {
    const twiml = new VoiceResponse();

    twiml.connect().stream({
      url: `wss://${process.env.SERVER_DOMAIN}/call/connection`,
    });

    res.writeHead(200, { 'Content-Type': 'text/xml' });
    res.end(twiml.toString());
  });

  app.ws('/call/connection', (ws: WebSocket) => {
    ws.on('message', async (data: string) => {
      const message: {
        event: string;
        start?: { streamSid: string; callSid: string };
      } = JSON.parse(data);

      if (message.event === 'start' && message.start) {
        const streamSid = message.start.streamSid;
        const response = await elevenlabs.textToSpeech.convert(voiceId, {
          modelId: 'eleven_flash_v2_5',
          outputFormat: outputFormat,
          text,
        });

        const readableStream = Readable.from(response);
        const audioArrayBuffer = await streamToArrayBuffer(readableStream);

        ws.send(
          JSON.stringify({
            streamSid,
            event: 'media',
            media: {
              payload: Buffer.from(audioArrayBuffer as any).toString('base64'),
            },
          })
        );
      }
    });

    ws.on('error', console.error);
  });

  app.listen(PORT, () => {
    console.log(`Local: http://localhost:${PORT}`);
    console.log(`Remote: https://${process.env.SERVER_DOMAIN}`);
  });
}

function streamToArrayBuffer(readableStream: Readable) {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];

    readableStream.on('data', (chunk) => {
      chunks.push(chunk);
    });

    readableStream.on('end', () => {
      resolve(Buffer.concat(chunks).buffer);
    });

    readableStream.on('error', reject);
  });
}

startApp();
```

```env
# .env
SERVER_DOMAIN=
ELEVENLABS_API_KEY=
```

## Understanding the code

### Handling the incoming call

When you call your number, Twilio makes a POST request to your endpoint at `/call/incoming`.
We then use twiml.connect to tell Twilio that we want to handle the call via our websocket by setting the url to our `/call/connection` endpoint.

```ts
function startApp() {
  app.post('/call/incoming', (_, res: Response) => {
    const twiml = new VoiceResponse();

    twiml.connect().stream({
      url: `wss://${process.env.SERVER_DOMAIN}/call/connection`,
    });

    res.writeHead(200, { 'Content-Type': 'text/xml' });
    res.end(twiml.toString());
  });
```

### Creating the text to speech

Here we listen for messages that Twilio sends to our websocket endpoint. When we receive a `start` message event, we generate audio using the ElevenLabs [TypeScript SDK](https://github.com/elevenlabs/elevenlabs-js).

```ts
  app.ws('/call/connection', (ws: WebSocket) => {
    ws.on('message', async (data: string) => {
      const message: {
        event: string;
        start?: { streamSid: string; callSid: string };
      } = JSON.parse(data);

      if (message.event === 'start' && message.start) {
        const streamSid = message.start.streamSid;
        const response = await elevenlabs.textToSpeech.convert(voiceId, {
          modelId: 'eleven_flash_v2_5',
          outputFormat: outputFormat,
          text,
        });
```

### Sending the message

Upon receiving the audio back from ElevenLabs, we convert it to an array buffer and send the audio to Twilio via the websocket.

```ts
const readableStream = Readable.from(response);
const audioArrayBuffer = await streamToArrayBuffer(readableStream);

ws.send(
  JSON.stringify({
    streamSid,
    event: 'media',
    media: {
      payload: Buffer.from(audioArrayBuffer as any).toString('base64'),
    },
  })
);
```

## Point ngrok to your application

Twilio requires a publicly accessible URL. We’ll use ngrok to forward the local port of our application and expose it as a public URL.

Run the following command in your terminal:

```
ngrok http 5000
```

Copy the ngrok domain (without https\://) to use in your environment variables.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/830a701ecee4b2bd32f44a891806a91e00f27dcf263c5917fa20a91a3353d6a1/assets/images/cookbooks/ngrok.webp" />

## Update your environment variables

Update the `.env` file with your ngrok domain and ElevenLabs API key.

```
# .env
SERVER_DOMAIN=*******.ngrok.app
ELEVENLABS_API_KEY=*************************
```

## Start the application

Run the following command to start the app:

```
npm run dev
```

## Set up Twilio

Follow Twilio’s guides to create a new number. Once you’ve created your number, navigate to the “Configure” tab in Phone Numbers -> Manage -> Active numbers

In the “A call comes in” section, enter the full URL to your application (make sure to add the`/call/incoming` path):

E.g. https\://**\*\*\***&#x6E;grok.app/call/incoming

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/8f57f550bca8ac451980d98482ff5877c4f8fac30035e712cd0375a6527686ff/assets/images/cookbooks/twilio.webp" />

## Make a phone call

Make a call to your number. You should hear a message using the ElevenLabs voice.

## Tips for deploying to production

When running the application in production, make sure to set the `SERVER_DOMAIN` environment variable to that of your server. Be sure to also update the URL in Twilio to point to your production server.

## Conclusion

You should now have a basic understanding of integrating Twilio with ElevenLabs voices. If you have any further questions, or suggestions on how to improve this blog post, please feel free to select the “Suggest edits” or “Raise issue” button below.


# Speech to Text quickstart

> Learn how to convert spoken audio into text.

This guide will show you how to convert spoken audio into text using the Speech to Text API.

<Info>
  This guide will demonstrate how to use the Batch Speech to Text API. For a guide on how to use the
  Realtime Speech to Text API, see the [Client-side
  streaming](/docs/developer-guides/cookbooks/speech-to-text/client-side-streaming) or [Server-side
  streaming](/docs/developer-guides/cookbooks/speech-to-text/server-side-streaming) guides.
</Info>

## Using the Speech to Text API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from io import BytesIO
      import requests
      from elevenlabs.client import ElevenLabs

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio_url = (
          "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      )
      response = requests.get(audio_url)
      audio_data = BytesIO(response.content)

      transcription = elevenlabs.speech_to_text.convert(
          file=audio_data,
          model_id="scribe_v2", # Model to use
          tag_audio_events=True, # Tag audio events like laughter, applause, etc.
          language_code="eng", # Language of the audio file. If set to None, the model will detect the language automatically.
          diarize=True, # Whether to annotate who is speaking
      )

      print(transcription)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const response = await fetch(
        "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      );
      const audioBlob = new Blob([await response.arrayBuffer()], { type: "audio/mp3" });

      const transcription = await elevenlabs.speechToText.convert({
        file: audioBlob,
        modelId: "scribe_v2", // Model to use
        tagAudioEvents: true, // Tag audio events like laughter, applause, etc.
        languageCode: "eng", // Language of the audio file. If set to null, the model will detect the language automatically.
        diarize: true, // Whether to annotate who is speaking
      });

      console.log(transcription);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should see the transcription of the audio file printed to the console.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/speech-to-text/convert) for more information on the Speech to Text API and its options.


# Multichannel speech-to-text

> Learn how to leverage the multichannel transcription mode.

## Overview

The multichannel Speech to Text feature enables you to transcribe audio files where each channel contains a distinct speaker. This is particularly useful for recordings where speakers are isolated on separate audio channels, providing cleaner transcriptions without the need for speaker diarization.

Each channel is processed independently and automatically assigned a speaker ID based on its channel number (channel 0 → `speaker_0`, channel 1 → `speaker_1`, etc.). The system extracts individual channels from your input audio file and transcribes them in parallel, combining the results sorted by timestamp.

### Common use cases

* **Stereo interview recordings** - Interviewer on left channel, interviewee on right channel
* **Multi-track podcast recordings** - Each participant recorded on a separate track
* **Call center recordings** - Agent and customer separated on different channels
* **Conference recordings** - Individual participants isolated on separate channels
* **Court proceedings** - Multiple parties recorded on distinct channels

## Requirements

* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys)
* Multichannel audio file (WAV, MP3, or other supported formats)
* Maximum 5 channels per audio file
* Each channel should contain only one speaker

## How it works

<Steps>
  <Step title="Prepare your multichannel audio">
    Ensure your audio file has speakers isolated on separate channels. The multichannel feature supports up to 5 channels, with each channel mapped to a specific speaker:

    * Channel 0 → `speaker_0`
    * Channel 1 → `speaker_1`
    * Channel 2 → `speaker_2`
    * Channel 3 → `speaker_3`
    * Channel 4 → `speaker_4`
  </Step>

  <Step title="Configure API parameters">
    When making a speech-to-text request, you must set:

    * `use_multi_channel`: `true`
    * `diarize`: `false` (multichannel mode handles speaker separation via channels)

    The `num_speakers` parameter cannot be used with multichannel mode as the speaker count is automatically determined by the number of channels. Multichannel mode assumes there will exactly one speaker per channel. If there are more, it will assign the same speaker id to all speakers in the channel.
  </Step>

  <Step title="Process the response">
    The API returns a different response format for multichannel audio:

    <Note>
      If you set `use_multi_channel: true` but provide a single-channel (mono) audio file, you'll
      receive a standard single-channel response, not the multichannel format. The multichannel response
      format is only returned when the audio file actually contains multiple channels.
    </Note>

    <CodeBlocks>
      ```python title="Single channel response"
      {
        "language_code": "en",
        "language_probability": 0.98,
        "text": "Hello world",
        "words": [...]
      }
      ```

      ```python title="Multichannel response"
      {
        "transcripts": [
          {
            "language_code": "en",
            "language_probability": 0.98,
            "text": "Hello from channel one.",
            "channel_index": 0,
            "words": [...]
          },
          {
            "language_code": "en",
            "language_probability": 0.97,
            "text": "Greetings from channel two.",
            "channel_index": 1,
            "words": [...]
          }
        ]
      }
      ```
    </CodeBlocks>
  </Step>
</Steps>

## Implementation

### Basic multichannel transcription

Here's a complete example of transcribing a stereo audio file with two speakers:

<CodeBlocks>
  ```python title="Python"
  from elevenlabs import ElevenLabs

  elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

  def transcribe_multichannel(audio_file_path):
      with open(audio_file_path, 'rb') as audio_file:
          result = elevenlabs.speech_to_text.convert(
              file=audio_file,
              model_id='scribe_v2',
              use_multi_channel=True,
              diarize=False,
              timestamps_granularity='word'
          )
      return result

  # Process the response

  result = transcribe_multichannel('stereo_interview.wav')

  if hasattr(result, 'transcripts'): # Multichannel response
      for transcript in result.transcripts:
          channel = transcript.channel_index
          text = transcript.text
          print(f"Channel {channel} (speaker_{channel}): {text}")
      else: # Single channel response (fallback)
          print(f"Text: {result.text}")

  ```

  ```javascript title="JavaScript"
  import { ElevenLabsClient } from 'elevenlabs';
  import fs from 'fs';

  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY,
  });

  async function transcribeMultichannel(audioFilePath) {
    try {
      const audioFile = fs.createReadStream(audioFilePath);

      const result = await elevenlabs.speechToText.convert({
        file: audioFile,
        modelId: 'scribe_v2',
        useMultiChannel: true,
        diarize: false,
        timestampsGranularity: 'word',
      });

      if (result.transcripts) {
        // Multichannel response
        result.transcripts.forEach((transcript, index) => {
          console.log(`Channel ${transcript.channel_index}: ${transcript.text}`);
        });
      } else {
        // Single channel response
        console.log(`Text: ${result.text}`);
      }

      return result;
    } catch (error) {
      console.error('Error transcribing audio:', error);
      throw error;
    }
  }
  ```

  ```bash title="cURL"
  curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
    -H "xi-api-key: YOUR_API_KEY" \
    -F "file=@stereo_audio_file.wav" \
    -F "model_id=scribe_v2" \
    -F "use_multi_channel=true" \
    -F "diarize=false" \
    -F "timestamps_granularity=word"
  ```
</CodeBlocks>

### Creating conversation transcripts

Generate a time-ordered conversation transcript from multichannel audio:

```python
def create_conversation_transcript(multichannel_result):
    """Create a conversation-style transcript with speaker labels"""
    all_words = []

    if hasattr(multichannel_result, 'transcripts'):
        # Collect all words from all channels
        for transcript in multichannel_result.transcripts:
            for word in transcript.words or []:
                if word.type == 'word':
                    all_words.append({
                        'text': word.text,
                        'start': word.start,
                        'speaker_id': word.speaker_id,
                        'channel': transcript.channel_index
                    })

    # Sort by timestamp
    all_words.sort(key=lambda w: w['start'])

    # Group consecutive words by speaker
    conversation = []
    current_speaker = None
    current_text = []

    for word in all_words:
        if word['speaker_id'] != current_speaker:
            if current_text:
                conversation.append({
                    'speaker': current_speaker,
                    'text': ' '.join(current_text)
                })
            current_speaker = word['speaker_id']
            current_text = [word['text']]
        else:
            current_text.append(word['text'])

    # Add the last segment
    if current_text:
        conversation.append({
            'speaker': current_speaker,
            'text': ' '.join(current_text)
        })

    return conversation

# Format the output
conversation = create_conversation_transcript(result)
for turn in conversation:
    print(f"{turn['speaker']}: {turn['text']}")
```

## Using webhooks with multichannel

Multichannel transcription fully supports [webhook delivery](/docs/developers/guides/cookbooks/speech-to-text/batch/webhooks) for asynchronous processing:

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

async def transcribe_multichannel_with_webhook(audio_file_path):
    with open(audio_file_path, 'rb') as audio_file:
        result = await elevenlabs.speech_to_text.convert_async(
            file=audio_file,
            model_id='scribe_v2',
            use_multi_channel=True,
            diarize=False,
            webhook=True  # Enable webhook delivery
        )

    print(f"Transcription started with task ID: {result.task_id}")
    return result.task_id
```

## Error handling

### Common validation errors

<AccordionGroup>
  <Accordion title="Setting diarize=true with multichannel mode">
    **Error**: Multichannel mode does not support diarization and assigns speakers based on the
    channel they speak on.

    **Solution**: Always set `diarize=false` when using multichannel mode.
  </Accordion>

  <Accordion title="Providing num_speakers parameter">
    **Error**: Cannot specify num\_speakers when use\_multi\_channel is enabled. The number of speakers
    is automatically determined by the number of channels. **Solution**: Remove the `num_speakers`
    parameter from your request.
  </Accordion>

  <Accordion title="Audio file with more than 5 channels">
    **Error**: Multichannel mode supports up to 5 channels, but the audio file contains X channels.

    **Solution**: Process only the first 5 channels or pre-process your audio to reduce channel
    count.
  </Accordion>
</AccordionGroup>

## Best practices

### Audio preparation

<Tip>
  For optimal results: - Use 16kHz sample rate for better performance - Remove silent or unused
  channels before processing - Ensure each channel contains only one speaker - Use lossless formats
  (WAV) when possible for best quality
</Tip>

### Performance optimization

The concurrency cost increases linearly with the number of channels. A 60-second 3-channel file has 3x the concurrency cost of a single-channel file.

You can estimate the processing time for multichannel audio using the following formula:

$$
Processing\ Time = (D \cdot 0.3) + 2 + (N \cdot 0.5)
$$

Where:

* $D$ = file duration in seconds
* $N$ = number of channels
* $0.3$ = processing speed factor (approximately 30% of real-time)
* $2$ = fixed overhead in seconds
* $0.5$ = per-channel overhead in seconds

**Example**: For a 60-second stereo file (2 channels):

$$
Processing\ Time = (60 \cdot 0.3) + 2 + (2 \cdot 0.5) = 18 + 2 + 1 = 21\ seconds
$$

### Memory considerations

For large multichannel files, consider streaming or chunking:

<CodeBlocks>
  ```python title="Python"
  def process_large_multichannel_file(file_path, chunk_duration=300):
      """Process large files in chunks (5-minute segments)"""

      from pydub import AudioSegment
      from elevenlabs import ElevenLabs
      import os

      elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
      audio = AudioSegment.from_file(file_path)
      duration_ms = len(audio)
      chunk_size_ms = chunk_duration * 1000

      all_transcripts = []

      for start_ms in range(0, duration_ms, chunk_size_ms):
          end_ms = min(start_ms + chunk_size_ms, duration_ms)

          # Extract chunk
          chunk = audio[start_ms:end_ms]
          chunk_file = f"temp_chunk_{start_ms}.wav"
          chunk.export(chunk_file, format="wav")

          # Transcribe chunk using SDK
          with open(chunk_file, 'rb') as audio_file:
              result = elevenlabs.speech_to_text.convert(
                  file=audio_file,
                  model_id='scribe_v2',
                  use_multi_channel=True,
                  diarize=False,
                  timestamps_granularity='word'
              )

          # Adjust timestamps
          if hasattr(result, 'transcripts'):
              for transcript in result.transcripts:
                  for word in transcript.words or []:
                      word.start += start_ms / 1000
                      word.end += start_ms / 1000
              all_transcripts.extend(result.transcripts)

          # Clean up
          os.remove(chunk_file)

      return all_transcripts

  ```

  ```javascript title="JavaScript"
  import { exec } from 'child_process';
  import { ElevenLabsClient } from 'elevenlabs';
  import fs from 'fs';
  import path from 'path';
  import { promisify } from 'util';

  const execAsync = promisify(exec);
  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY,
  });

  async function processLargeMultichannelFile(filePath, chunkDuration = 300) {
    /**
     * Process large files in chunks (5-minute segments)
     * Requires ffmpeg to be installed
     */

    // Get audio duration using ffprobe
    const { stdout } = await execAsync(
      `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${filePath}"`
    );
    const durationSeconds = parseFloat(stdout);

    const allTranscripts = [];

    for (let startSeconds = 0; startSeconds < durationSeconds; startSeconds += chunkDuration) {
      const endSeconds = Math.min(startSeconds + chunkDuration, durationSeconds);
      const chunkFile = path.join(path.dirname(filePath), `temp_chunk_${startSeconds}.wav`);

      // Extract chunk using ffmpeg
      await execAsync(
        `ffmpeg -i "${filePath}" -ss ${startSeconds} -t ${chunkDuration} -c:a pcm_s16le "${chunkFile}" -y`
      );

      try {
        // Transcribe chunk
        const audioFile = fs.createReadStream(chunkFile);
        const result = await elevenlabs.speechToText.convert({
          file: audioFile,
          modelId: 'scribe_v2',
          useMultiChannel: true,
          diarize: false,
          timestampsGranularity: 'word',
        });

        // Adjust timestamps
        if (result.transcripts) {
          for (const transcript of result.transcripts) {
            for (const word of transcript.words || []) {
              word.start += startSeconds;
              word.end += startSeconds;
            }
          }
          allTranscripts.push(...result.transcripts);
        }
      } finally {
        // Clean up
        fs.unlinkSync(chunkFile);
      }
    }

    return { transcripts: allTranscripts };
  }
  ```
</CodeBlocks>

## FAQ

<AccordionGroup>
  <Accordion title="What happens if my audio has more than 5 channels?">
    The API will return an error. You'll need to either select which 5 channels to send to the API
    or mix down some channels before sending them to the API.
  </Accordion>

  <Accordion title="Can I process mono audio with multichannel mode?">
    Yes, but it's unnecessary. If you send mono audio with `use_multi_channel=true`, you'll receive
    a standard single-channel response, not the multichannel format.
  </Accordion>

  <Accordion title="How are speaker IDs assigned?">
    Speaker IDs are deterministic based on channel number: channel 0 becomes speaker\_0, channel 1
    becomes speaker\_1, and so on.
  </Accordion>

  <Accordion title="Can channels have different languages?">
    Yes, each channel is processed independently and can detect different languages. The language
    detection happens per channel.
  </Accordion>
</AccordionGroup>


# Asynchronous Speech to Text

> Learn how to use webhooks to receive asynchronous notifications when your transcription tasks are completed.

## Overview

Webhooks allow you to receive automatic notifications when your Speech to Text transcription tasks are completed, eliminating the need to continuously poll the API for status updates. This is particularly useful for long-running transcription jobs or when processing large volumes of audio files.

When a transcription is completed, ElevenLabs will send a POST request to your specified webhook URL with the transcription results, including the transcript text, language detection, and any metadata.

## Using webhooks

<Steps>
  <Step title="Create a webhook endpoint">
    First, create a webhook in the ElevenLabs dashboard. Navigate to your [webhooks settings](https://elevenlabs.io/app/settings/webhooks) and click "Create Webhook".

    <Frame background="subtle" caption="Create a new webhook in the ElevenLabs dashboard">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/fe9e1aa443fa407054e9d1a2755d7a757905b566b50eafbe8e6c0b138fdea875/assets/images/cookbooks/scribe/webhooks/create-webhook.png" alt="Create webhook interface" />
    </Frame>

    Configure your webhook with:

    * **Name**: A descriptive name for your webhook
    * **Callback URL**: Your publicly accessible HTTPS endpoint
    * **Webhook Auth Method**: Either `HMAC` or `OAuth`. It is up to the client to implement the verification mechanism. ElevenLabs sends headers that allow for verification but we do not enforce it.
  </Step>

  <Step title="Associate webhook with transcription tasks">
    Once created, you can associate the webhook with your speech-to-text tasks. In the dashboard, navigate to the webhook events section and link your webhooks to speech-to-text events.

    <Frame background="subtle" caption="Associate webhook with speech-to-text tasks">
      <img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/28fc58a2a638abb54ab14346e150933e969584f181d72eeda242588e0786d1e9/assets/images/cookbooks/scribe/webhooks/associate-webhook.png" alt="Webhook association interface" />
    </Frame>
  </Step>

  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make API calls with webhook parameter enabled">
    When making speech-to-text API calls, include the `webhook` parameter set to `true` to enable webhook notifications for that specific request.

    <CodeBlocks>
      ```python maxLines=0
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      def transcribe_with_webhook(audio_file):
        try:
          result = elevenlabs.speech_to_text.convert(
            file=audio_file,
            model_id="scribe_v2",
            webhook=True,
          )
          print(f"Transcription started: {result.request_id}")
          return result
        except Exception as e:
          print(f"Error starting transcription: {e}")
          raise e
      ```

      ```typescript maxLines=0
      import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

      const elevenlabs = new ElevenLabsClient({
        apiKey: process.env.ELEVENLABS_API_KEY,
      });

      async function transcribeWithWebhook(audioFile) {
        try {
          const result = await elevenlabs.speechToText.convert({
            file: audioFile,
            modelId: 'scribe_v2',
            webhook: true,
          });

          console.log('Transcription started:', result.requestId);
          return result;
        } catch (error) {
          console.error('Error starting transcription:', error);
          throw error;
        }
      }
      ```
    </CodeBlocks>
  </Step>
</Steps>

## Webhook payload

When a transcription is completed, your webhook endpoint will receive a POST request with the transcription and webhook data:

```json
{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    transcription: {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}
```

Please refer to the [Speech-to-text API](/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime) reference to learn about the details of the response structure.

## Implementing your webhook endpoint

Here's an example of how to implement a webhook endpoint to handle incoming notifications:

```javascript
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express from 'express';

const elevenlabs = new ElevenLabsClient();

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;

    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;

      console.log(`Transcription ${requestId} completed`);
      console.log(`Language: ${language_code}`);
      console.log(`Text: ${text}`);

      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

async function processTranscription(requestId, text, language) {
  console.log('Processing completed transcription...');
}

async function handleTranscriptionError(requestId) {
  console.log('Handling transcription error...');
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});
```

## Security considerations

### Signature verification

Always verify webhook signatures to ensure requests came from ElevenLabs.

### HTTPS requirement

Webhook URLs must use HTTPS to ensure secure transmission of transcription data.

### Rate limiting

Implement rate limiting on your webhook endpoint to prevent abuse:

```javascript
import rateLimit from 'express-rate-limit';

const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: 'Too many webhook requests from this IP',
});

app.use('/webhook', webhookLimiter);
```

### Failure responses

Return appropriate HTTP status codes:

* `200-299`: Success - webhook processed successfully
* `400-499`: Client error - webhook will not be retried
* `500-599`: Server error - webhook will be retried

## Testing webhooks

### Local development

For local testing, use tools like [ngrok](https://ngrok.com/) to expose your local server:

```bash
ngrok http 3000
```

Use the provided HTTPS URL as your webhook endpoint during development.

### Webhook testing

You can test your webhook implementation by making a transcription request and monitoring your endpoint:

```javascript
async function testWebhook() {
  const audioFile = new File([audioBuffer], 'test.mp3', { type: 'audio/mp3' });

  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: 'scribe_v2',
    webhook: true,
  });

  console.log('Test transcription started:', result.requestId);
}
```


# Keyterm prompting

> Learn how to use keyterm prompting with the Speech to Text API

## Overview

<Warning>
  Keyterm prompting is only available with the Scribe v2 model and comes at an additional cost. See
  the [API pricing
  page](https://elevenlabs.io/pricing?price.section=speech_to_text\&price.sections=speech_to_text,speech_to_text#pricing-table)
  for detailed pricing information.
</Warning>

Keyterm prompting is a feature that allows you to highlight up to 100 words or phrases to bias the model towards transcribing them. This is useful for transcribing specific words or sentences that are not common in the audio, such as product names, names, or other specific terms. Keyterms are more powerful than biased keywords or customer vocabularies offered by other models, because it relies on the context to decide whether to transcribe that term or not.

For example, if your company name is not a common phrase or has a unique spelling or pronunciation you can use keyterms to ensure the model transcribes correctly. Take the following audio:

<elevenlabs-audio-player audio-title="Company name example" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3" />

Without keyterm prompting, the model might transcribe the above as:

```
I work at eleven labs.
```

Which uses the wrong style for the company name. With keyterm prompting, you can ensure the model transcribes the above with the correct spelling and style:

```
I work at ElevenLabs.
```

### Context

The model is able to use context to determine whether a term should be transcribed or not. When providing the keyterm "ElevenLabs", the above audio transcribes as expected, yet the model will still be able to transcribe the following correctly based on the context:

<elevenlabs-audio-player audio-title="Context example" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting-context.mp3" />

Which outputs the following transcription:

```
I've worked at many labs. In fact I've worked at eleven labs.
```

## Integrating keyterm prompting

Keyterm prompting is integrated into the Speech to Text API by passing the `keyterms` parameter to the `convert` method.

<CodeBlocks>
  ```python maxLines=0 {22-24}
  import os
  from dotenv import load_dotenv
  from io import BytesIO
  import requests
  from elevenlabs.client import ElevenLabs

  load_dotenv()

  elevenlabs = ElevenLabs(
      api_key=os.getenv("ELEVENLABS_API_KEY"),
  )

  audio_url = (
      "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
  )
  response = requests.get(audio_url)
  audio_data = BytesIO(response.content)

  transcription = elevenlabs.speech_to_text.convert(
      file=audio_data,
      model_id="scribe_v2", # Model to use
      # Keyterms to prompt the model with.
      # Up to 100 keyterms can be provided, with a maximum length of 50 characters each
      keyterms=["ElevenLabs"],
  )

  print(transcription)
  ```

  ```typescript maxLines=0 {16-18}
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
  import 'dotenv/config';

  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY,
  });

  const response = await fetch(
    'https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3'
  );
  const audioBlob = new Blob([await response.arrayBuffer()], { type: 'audio/mp3' });

  const transcription = await elevenlabs.speechToText.convert({
    file: audioBlob,
    modelId: 'scribe_v2', // Model to use
    // Keyterms to prompt the model with.
    // Up to 100 keyterms can be provided, with a maximum length of 50 characters each
    keyterms: ['ElevenLabs'],
  });

  console.log(transcription);
  ```
</CodeBlocks>


# Entity detection

> Learn how to use entity detection with the Speech to Text API

## Overview

<Warning>
  Entity detection comes at an additional cost. See the [API pricing
  page](https://elevenlabs.io/pricing?price.section=speech_to_text\&price.sections=speech_to_text,speech_to_text#pricing-table)
  for detailed pricing information.
</Warning>

Entity detection is a feature that allows you to detect specific words and phrases in the transcript, providing their exact timestamps. This is useful to detect credit card numbers, names, medical conditions or SSNs which can then be redacted.

When enabled, the model will detect specific entity types in the transcript and provide their exact timestamps.

For example, the following audio:

<elevenlabs-audio-player audio-title="Entity detection example" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-entity-detection-pii.mp3" />

Outputs the following transcript when we specify `"pii"` (Personally Identifiable Information) as the entity type:

```json maxLines=0
{
  "language_code": "eng",
  "language_probability": 0.9869821071624756,
  "text": "My name is Jill. My date of birth is the 12th of July 1987, and my credit card number is 4242-4242-4242-4242.",
  "words": [
    { "text": "My", "start": 0.099, "end": 0.259, "type": "word", "logprob": 0.0 },
    { "text": " ", "start": 0.259, "end": 0.299, "type": "spacing", "logprob": 0.0 },
    { "text": "name", "start": 0.299, "end": 0.42, "type": "word", "logprob": 0.0 },
    ...
  ],
  "transcription_id": "Y2ZX8AxHUzTPCIualYiE",
  "entities": [
    {
      "text": "Jill",
      "entity_type": "name",
      "start_char": 11,
      "end_char": 15
    },
    {
      "text": "12th of July 1987",
      "entity_type": "dob",
      "start_char": 41,
      "end_char": 58
    },
    {
      "text": "4242-4242-4242-4242",
      "entity_type": "credit_card",
      "start_char": 89,
      "end_char": 108
    }
  ]
}
```

The result shows the PII entities detected in the transcript, with their exact timestamps.

## Integrating entity detection

Entity detection is integrated into the Speech to Text API by passing the `entity_detection` parameter to the `convert` method.

<CodeBlocks>
  ```python maxLines=0
  import os
  from dotenv import load_dotenv
  from io import BytesIO
  import requests
  from elevenlabs.client import ElevenLabs

  load_dotenv()

  elevenlabs = ElevenLabs(
      api_key=os.getenv("ELEVENLABS_API_KEY"),
  )

  audio_url = (
      "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-entity-detection-pii.mp3"
  )
  response = requests.get(audio_url)
  audio_data = BytesIO(response.content)

  transcription = elevenlabs.speech_to_text.convert(
      file=audio_data,
      model_id="scribe_v2", # Model to use
      # Entity types to detect, accepts a list of specific entity types or categories.
      # To detect all entity types, use the "all" category.
      entity_detection=["pii"],
  )

  print("Entities detected:", transcription.entities)
  ```

  ```typescript maxLines=0
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
  import 'dotenv/config';

  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY,
  });

  const response = await fetch(
    'https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-entity-detection-pii.mp3'
  );
  const audioBlob = new Blob([await response.arrayBuffer()], { type: 'audio/mp3' });

  const transcription = await elevenlabs.speechToText.convert({
    file: audioBlob,
    modelId: 'scribe_v2', // Model to use
    // Entity types to detect, accepts a list of specific entity types or categories.
    // To detect all entity types, use the "all" category.
    entityDetection: ['pii'],
  });

  console.log('Entities detected:', transcription.entities);
  ```
</CodeBlocks>

## Entity types

The following entity types are supported for detection. You can detect entire groups using `pii`, `phi`, or `pci`, or specify individual entity types by their label. To detect all entity types, use the `all` category.

<AccordionGroup>
  <Accordion title="PII (Personally Identifiable Information)">
    <div>
      | Label                       | Description                                                                                  | Regulatory Compliance                                          |
      | --------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
      | `account_number`            | Customer account or membership identification number                                         | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `age`                       | Numbers associated with an individual's age                                                  | GDPR, HIPAA, Quebec Privacy Act, APPI                          |
      | `bank_account`              | Bank account numbers and international equivalents, such as IBAN                             | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `cardinal`                  | Numerical expressions in cardinal form                                                       |                                                                |
      | `credit_card`               | Credit card numbers                                                                          | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `credit_card_expiration`    | Expiration date of a credit card                                                             | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `cvv`                       | 3- or 4-digit card verification codes and equivalents                                        | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `date`                      | Specific calendar dates, which can include days of the week, dates, months, or years         | HIPAA, Quebec Privacy Act                                      |
      | `date_interval`             | Broader time periods, including date ranges, months, seasons, years, and decades             | HIPAA                                                          |
      | `dob`                       | Dates of birth                                                                               | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `driver_license`            | Driver's permit numbers                                                                      | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `email_address`             | Email addresses                                                                              | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `event`                     | Names of events or holidays                                                                  |                                                                |
      | `filename`                  | Names of computer files, including the extension or filepath                                 |                                                                |
      | `gender_sexuality`          | Terms indicating gender identity or sexual orientation, including slang terms                | CPRA, GDPR, GDPR Sensitive, APPI Sensitive                     |
      | `healthcare_number`         | Healthcare numbers and health plan beneficiary numbers                                       | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `ip_address`                | Internet IP address, including IPv4 and IPv6 formats                                         | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `location`                  | Metaclass for any named location reference                                                   | GDPR, HIPAA, APPI                                              |
      | `location_address`          | Full or partial physical mailing addresses                                                   | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `location_city`             | Municipality names, including villages, towns, and cities                                    | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `location_coordinate`       | Geographic positions referred to using latitude, longitude, and/or elevation coordinates     | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `location_country`          | Country names                                                                                | GDPR, APPI                                                     |
      | `location_state`            | State, province, territory, or prefecture names                                              | GDPR, APPI                                                     |
      | `location_zip`              | ZIP codes (including ZIP+4), postcodes, or postal codes                                      | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `money`                     | Names and/or amounts of currency                                                             |                                                                |
      | `name`                      | Names of individuals, not including personal titles such as 'Mrs.' or 'Mr.'                  | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `name_given`                | Names given to an individual, usually at birth; often first/middle names in Western cultures | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `name_family`               | Names indicating a person's family or community; often a last name in Western cultures       | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `name_medical_professional` | Names including the title of a medical professional, such as "Doctor"                        | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `numerical_pii`             | Numerical PII that doesn't fall under other categories                                       | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `occupation`                | Job titles or professions                                                                    | Quebec Privacy Act, APPI                                       |
      | `ordinal`                   | Numerical expressions in ordinal form                                                        |                                                                |
      | `origin`                    | Terms indicating nationality, ethnicity, or provenance                                       | CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive |
      | `passport_number`           | Passport numbers, issued by any country                                                      | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `password`                  | Account passwords, PINs, access keys, or verification answers                                | CPRA, APPI                                                     |
      | `percent`                   | Numerical expressions as percentages                                                         |                                                                |
      | `phone_number`              | Telephone or fax numbers                                                                     | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `physical_attribute`        | Distinctive bodily attributes, including terms indicating race                               | CPRA, GDPR, GDPR Sensitive, APPI Sensitive                     |
      | `ssn`                       | Social Security Numbers or international equivalent government identification numbers        | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI                    |
      | `time`                      | Expressions indicating clock times                                                           |                                                                |
      | `url`                       | Internet addresses                                                                           | CPRA, GDPR, HIPAA, Quebec Privacy Act                          |
      | `username`                  | Usernames, login names, or handles                                                           | CPRA, GDPR, APPI                                               |
      | `vehicle_id`                | Vehicle identification numbers (VINs), vehicle serial numbers, and license plate numbers     | CPRA, GDPR, HIPAA, APPI                                        |
    </div>
  </Accordion>

  <Accordion title="PHI (Protected Health Information)">
    <div>
      | Label             | Description                                                           | Regulatory Compliance                                 |
      | ----------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
      | `condition`       | Names of medical conditions, diseases, syndromes, deficits, disorders | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive |
      | `drug`            | Medications, vitamins, and supplements                                | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive |
      | `injury`          | Bodily injuries, including mutations, miscarriages, and dislocations  | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive |
      | `blood_type`      | Blood types                                                           | CPRA, GDPR, HIPAA, Quebec Privacy Act                 |
      | `medical_process` | Medical processes, including treatments, procedures, and tests        | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive |
      | `statistics`      | Medical statistics                                                    | HIPAA, Quebec Privacy Act                             |
    </div>
  </Accordion>

  <Accordion title="PCI (Payment Card Industry)">
    <div>
      | Label                    | Description                                           | Regulatory Compliance                       |
      | ------------------------ | ----------------------------------------------------- | ------------------------------------------- |
      | `credit_card`            | Credit card numbers                                   | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI |
      | `credit_card_expiration` | Expiration date of a credit card                      | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI |
      | `cvv`                    | 3- or 4-digit card verification codes and equivalents | CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI |
    </div>
  </Accordion>

  <Accordion title="Other entities">
    <div>
      | Label                   | Description                                                    | Regulatory Compliance                                          |
      | ----------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
      | `language`              | Names of natural languages                                     | GDPR, GDPR Sensitive, APPI Sensitive                           |
      | `marital_status`        | Terms indicating marital status                                | APPI Sensitive                                                 |
      | `organization`          | Names of organizations or departments within an organization   | Quebec Privacy Act, APPI                                       |
      | `political_affiliation` | Terms referring to a political party, movement, or ideology    | CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive |
      | `religion`              | Terms indicating religious affiliation                         | CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive |
      | `routing_number`        | Routing number associated with a bank or financial institution |                                                                |
      | `zodiac_sign`           | Names of Zodiac signs                                          |                                                                |
    </div>
  </Accordion>
</AccordionGroup>


# Transcription Telegram Bot

> Build a Telegram bot that transcribes audio and video messages in 90+languages using TypeScript with Deno in Supabase Edge Functions.

## Introduction

In this tutorial you will learn how to build a Telegram bot that transcribes audio and video messages in 90+ languages using TypeScript and the ElevenLabs Scribe model via the speech-to-text API.

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/CE4iPp7kd7Q" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Tip title="Prefer to jump straight to the code?" icon="lightbulb">
  Find the [example project on
  GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/speech-to-text/telegram-transcription-bot).
</Tip>

## Requirements

* An ElevenLabs account with an [API key](https://elevenlabs.io/app/settings/api-keys).
* A [Supabase](https://supabase.com) account (you can sign up for a free account via [database.new](https://database.new)).
* The [Supabase CLI](https://supabase.com/docs/guides/local-development) installed on your machine.
* The [Deno runtime](https://docs.deno.com/runtime/getting_started/installation/) installed on your machine and optionally [setup in your facourite IDE](https://docs.deno.com/runtime/getting_started/setup_your_environment).
* A [Telegram](https://telegram.org) account.

## Setup

### Register a Telegram bot

Use the [BotFather](https://t.me/BotFather) to create a new Telegram bot. Run the `/newbot` command and follow the instructions to create a new bot. At the end, you will receive your secret bot token. Note it down securely for the next step.

![BotFather](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/28aa856bb6ace1b49b82076a18f1e281a8a4f37bbb6cfc59c22d644564377248/assets/images/cookbooks/scribe/telegram-bot/bot-father.png)

### Create a Supabase project locally

After installing the [Supabase CLI](https://supabase.com/docs/guides/local-development), run the following command to create a new Supabase project locally:

```bash
supabase init
```

### Create a database table to log the transcription results

Next, create a new database table to log the transcription results:

```bash
supabase migrations new init
```

This will create a new migration file in the `supabase/migrations` directory. Open the file and add the following SQL:

```sql supabase/migrations/init.sql
CREATE TABLE IF NOT EXISTS transcription_logs (
  id BIGSERIAL PRIMARY KEY,
  file_type VARCHAR NOT NULL,
  duration INTEGER NOT NULL,
  chat_id BIGINT NOT NULL,
  message_id BIGINT NOT NULL,
  username VARCHAR,
  transcript TEXT,
  language_code VARCHAR,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  error TEXT
);

ALTER TABLE transcription_logs ENABLE ROW LEVEL SECURITY;
```

### Create a Supabase Edge Function to handle Telegram webhook requests

Next, create a new Edge Function to handle Telegram webhook requests:

```bash
supabase functions new scribe-bot
```

If you're using VS Code or Cursor, select `y` when the CLI prompts "Generate VS Code settings for Deno? \[y/N]"!

### Set up the environment variables

Within the `supabase/functions` directory, create a new `.env` file and add the following variables:

```env supabase/functions/.env
# Find / create an API key at https://elevenlabs.io/app/settings/api-keys
ELEVENLABS_API_KEY=your_api_key

# The bot token you received from the BotFather.
TELEGRAM_BOT_TOKEN=your_bot_token

# A random secret chosen by you to secure the function.
FUNCTION_SECRET=random_secret
```

### Dependencies

The project uses a couple of dependencies:

* The open-source [grammY Framework](https://grammy.dev/) to handle the Telegram webhook requests.
* The [@supabase/supabase-js](https://supabase.com/docs/reference/javascript) library to interact with the Supabase database.
* The ElevenLabs [JavaScript SDK](/docs/developers/quickstart) to interact with the speech-to-text API.

Since Supabase Edge Function uses the [Deno runtime](https://deno.land/), you don't need to install the dependencies, rather you can [import](https://docs.deno.com/examples/npm/) them via the `npm:` prefix.

## Code the Telegram Bot

In your newly created `scribe-bot/index.ts` file, add the following code:

```ts supabase/functions/scribe-bot/index.ts
import { Bot, webhookCallback } from 'https://deno.land/x/grammy@v1.34.0/mod.ts';
import 'jsr:@supabase/functions-js/edge-runtime.d.ts';
import { createClient } from 'jsr:@supabase/supabase-js@2';
import { ElevenLabsClient } from 'npm:elevenlabs@1.50.5';

console.log(`Function "elevenlabs-scribe-bot" up and running!`);

const elevenlabs = new ElevenLabsClient({
  apiKey: Deno.env.get('ELEVENLABS_API_KEY') || '',
});

const supabase = createClient(
  Deno.env.get('SUPABASE_URL') || '',
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') || ''
);

async function scribe({
  fileURL,
  fileType,
  duration,
  chatId,
  messageId,
  username,
}: {
  fileURL: string;
  fileType: string;
  duration: number;
  chatId: number;
  messageId: number;
  username: string;
}) {
  let transcript: string | null = null;
  let languageCode: string | null = null;
  let errorMsg: string | null = null;
  try {
    const sourceFileArrayBuffer = await fetch(fileURL).then((res) => res.arrayBuffer());
    const sourceBlob = new Blob([sourceFileArrayBuffer], {
      type: fileType,
    });

    const scribeResult = await elevenlabs.speechToText.convert({
      file: sourceBlob,
      model_id: 'scribe_v2',
      tag_audio_events: false,
    });

    transcript = scribeResult.text;
    languageCode = scribeResult.language_code;

    // Reply to the user with the transcript
    await bot.api.sendMessage(chatId, transcript, {
      reply_parameters: { message_id: messageId },
    });
  } catch (error) {
    errorMsg = error.message;
    console.log(errorMsg);
    await bot.api.sendMessage(chatId, 'Sorry, there was an error. Please try again.', {
      reply_parameters: { message_id: messageId },
    });
  }
  // Write log to Supabase.
  const logLine = {
    file_type: fileType,
    duration,
    chat_id: chatId,
    message_id: messageId,
    username,
    language_code: languageCode,
    error: errorMsg,
  };
  console.log({ logLine });
  await supabase.from('transcription_logs').insert({ ...logLine, transcript });
}

const telegramBotToken = Deno.env.get('TELEGRAM_BOT_TOKEN');
const bot = new Bot(telegramBotToken || '');
const startMessage = `Welcome to the ElevenLabs Scribe Bot\\! I can transcribe speech in 90\\+ languages with super high accuracy\\!
    \nTry it out by sending or forwarding me a voice message, video, or audio file\\!
    \n[Learn more about Scribe](https://elevenlabs.io/speech-to-text) or [build your own bot](https://elevenlabs.io/developers/guides/cookbooks/speech-to-text/telegram-bot)\\!
  `;
bot.command('start', (ctx) => ctx.reply(startMessage.trim(), { parse_mode: 'MarkdownV2' }));

bot.on([':voice', ':audio', ':video'], async (ctx) => {
  try {
    const file = await ctx.getFile();
    const fileURL = `https://api.telegram.org/file/bot${telegramBotToken}/${file.file_path}`;
    const fileMeta = ctx.message?.video ?? ctx.message?.voice ?? ctx.message?.audio;

    if (!fileMeta) {
      return ctx.reply('No video|audio|voice metadata found. Please try again.');
    }

    // Run the transcription in the background.
    EdgeRuntime.waitUntil(
      scribe({
        fileURL,
        fileType: fileMeta.mime_type!,
        duration: fileMeta.duration,
        chatId: ctx.chat.id,
        messageId: ctx.message?.message_id!,
        username: ctx.from?.username || '',
      })
    );

    // Reply to the user immediately to let them know we received their file.
    return ctx.reply('Received. Scribing...');
  } catch (error) {
    console.error(error);
    return ctx.reply(
      'Sorry, there was an error getting the file. Please try again with a smaller file!'
    );
  }
});

const handleUpdate = webhookCallback(bot, 'std/http');

Deno.serve(async (req) => {
  try {
    const url = new URL(req.url);
    if (url.searchParams.get('secret') !== Deno.env.get('FUNCTION_SECRET')) {
      return new Response('not allowed', { status: 405 });
    }

    return await handleUpdate(req);
  } catch (err) {
    console.error(err);
  }
});
```

### Code deep dive

There's a couple of things worth noting about the code. Let's step through it step by step.

<Steps>
  <Step title="Handling the incoming request">
    To handle the incoming request, use the `Deno.serve` handler. The handler checks whether the request has the correct secret and then passes the request to the `handleUpdate` function.

    ```ts {1,6,10}
    const handleUpdate = webhookCallback(bot, 'std/http');

    Deno.serve(async (req) => {
      try {
        const url = new URL(req.url);
        if (url.searchParams.get('secret') !== Deno.env.get('FUNCTION_SECRET')) {
          return new Response('not allowed', { status: 405 });
        }

        return await handleUpdate(req);
      } catch (err) {
        console.error(err);
      }
    });
    ```
  </Step>

  <Step title="Handle voice, audio, and video messages">
    The grammY frameworks provides a convenient way to [filter](https://grammy.dev/guide/filter-queries#combining-multiple-queries) for specific message types. In this case, the bot is listening for voice, audio, and video messages.

    Using the request context, the bot extracts the file metadata and then uses [Supabase Background Tasks](https://supabase.com/docs/guides/functions/background-tasks) `EdgeRuntime.waitUntil` to run the transcription in the background.

    This way you can provide an immediate response to the user and handle the transcription of the file in the background.

    ```ts {1,3,12,24}
    bot.on([':voice', ':audio', ':video'], async (ctx) => {
      try {
        const file = await ctx.getFile();
        const fileURL = `https://api.telegram.org/file/bot${telegramBotToken}/${file.file_path}`;
        const fileMeta = ctx.message?.video ?? ctx.message?.voice ?? ctx.message?.audio;

        if (!fileMeta) {
          return ctx.reply('No video|audio|voice metadata found. Please try again.');
        }

        // Run the transcription in the background.
        EdgeRuntime.waitUntil(
          scribe({
            fileURL,
            fileType: fileMeta.mime_type!,
            duration: fileMeta.duration,
            chatId: ctx.chat.id,
            messageId: ctx.message?.message_id!,
            username: ctx.from?.username || '',
          })
        );

        // Reply to the user immediately to let them know we received their file.
        return ctx.reply('Received. Scribing...');
      } catch (error) {
        console.error(error);
        return ctx.reply(
          'Sorry, there was an error getting the file. Please try again with a smaller file!'
        );
      }
    });
    ```
  </Step>

  <Step title="Transcription with the ElevenLabs API">
    Finally, in the background worker, the bot uses the ElevenLabs JavaScript SDK to transcribe the file. Once the transcription is complete, the bot replies to the user with the transcript and writes a log entry to the Supabase database using [supabase-js](https://supabase.com/docs/reference/javascript).

    ```ts {29-38,43-46,54-65}
    const elevenlabs = new ElevenLabsClient({
      apiKey: Deno.env.get('ELEVENLABS_API_KEY') || '',
    });

    const supabase = createClient(
      Deno.env.get('SUPABASE_URL') || '',
      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') || ''
    );

    async function scribe({
      fileURL,
      fileType,
      duration,
      chatId,
      messageId,
      username,
    }: {
      fileURL: string;
      fileType: string;
      duration: number;
      chatId: number;
      messageId: number;
      username: string;
    }) {
      let transcript: string | null = null;
      let languageCode: string | null = null;
      let errorMsg: string | null = null;
      try {
        const sourceFileArrayBuffer = await fetch(fileURL).then((res) => res.arrayBuffer());
        const sourceBlob = new Blob([sourceFileArrayBuffer], {
          type: fileType,
        });

        const scribeResult = await elevenlabs.speechToText.convert({
          file: sourceBlob,
          model_id: 'scribe_v2',
          tag_audio_events: false,
        });

        transcript = scribeResult.text;
        languageCode = scribeResult.language_code;

        // Reply to the user with the transcript
        await bot.api.sendMessage(chatId, transcript, {
          reply_parameters: { message_id: messageId },
        });
      } catch (error) {
        errorMsg = error.message;
        console.log(errorMsg);
        await bot.api.sendMessage(chatId, 'Sorry, there was an error. Please try again.', {
          reply_parameters: { message_id: messageId },
        });
      }
      // Write log to Supabase.
      const logLine = {
        file_type: fileType,
        duration,
        chat_id: chatId,
        message_id: messageId,
        username,
        language_code: languageCode,
        error: errorMsg,
      };
      console.log({ logLine });
      await supabase.from('transcription_logs').insert({ ...logLine, transcript });
    }
    ```
  </Step>
</Steps>

## Deploy to Supabase

If you haven't already, create a new Supabase account at [database.new](https://database.new) and link the local project to your Supabase account:

```bash
supabase link
```

### Apply the database migrations

Run the following command to apply the database migrations from the `supabase/migrations` directory:

```bash
supabase db push
```

Navigate to the [table editor](https://supabase.com/dashboard/project/_/editor) in your Supabase dashboard and you should see and empty `transcription_logs` table.

![Empty table](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/c1493deafcd6c53712dcb4fa7a44b3253b571ade0bb2e9c2b4fdb090088b0695/assets/images/cookbooks/scribe/telegram-bot/supa-empty-table.png)

Lastly, run the following command to deploy the Edge Function:

```bash
supabase functions deploy --no-verify-jwt scribe-bot
```

Navigate to the [Edge Functions view](https://supabase.com/dashboard/project/_/functions) in your Supabase dashboard and you should see the `scribe-bot` function deployed. Make a note of the function URL as you'll need it later, it should look something like `https://<project-ref>.functions.supabase.co/scribe-bot`.

![Edge Function deployed](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/d12141a51a09563d625b379201de844800e0c7dcfa9e6c7f21484cbca7ff37cf/assets/images/cookbooks/scribe/telegram-bot/supa-edge-function-deployed.png)

### Set up the webhook

Set your bot's webhook url to `https://<PROJECT_REFERENCE>.functions.supabase.co/telegram-bot` (Replacing `<...>` with respective values). In order to do that, simply run a GET request to the following url (in your browser, for example):

```
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://<PROJECT_REFERENCE>.supabase.co/functions/v1/scribe-bot?secret=<FUNCTION_SECRET>
```

Note that the `FUNCTION_SECRET` is the secret you set in your `.env` file.

![Set webhook](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/ac72044bd3df138da3d8a0df09e8413e8a9fd8a5c3156a525d6b13664854482f/assets/images/cookbooks/scribe/telegram-bot/set-webhook.png)

### Set the function secrets

Now that you have all your secrets set locally, you can run the following command to set the secrets in your Supabase project:

```bash
supabase secrets set --env-file supabase/functions/.env
```

## Test the bot

Finally you can test the bot by sending it a voice message, audio or video file.

![Test the bot](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/a42c784e6324f15575e0299bafe02a253a2bdc57f2ad5844f83e5b64297780e7/assets/images/cookbooks/scribe/telegram-bot/test-bot.png)

After you see the transcript as a reply, navigate back to your table editor in the Supabase dashboard and you should see a new row in your `transcription_logs` table.

![New row in table](https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/25c008858276b7cd4af6f8e72473891176bb9e2ce62e7002af353a2dac205e06/assets/images/cookbooks/scribe/telegram-bot/supa-new-row.png)


# Vercel AI SDK

> Use the ElevenLabs Provider in the Vercel AI SDK to transcribe speech from audio and video files.

# ElevenLabs Provider

The [ElevenLabs provider](https://ai-sdk.dev/providers/ai-sdk-providers/elevenlabs) provides support for the [ElevenLabs transcription API](https://elevenlabs.io/speech-to-text).

## Setup

The ElevenLabs provider is available in the `@ai-sdk/elevenlabs` module. You can install it with npm:

```npm
npm install @ai-sdk/elevenlabs
```

## Provider Instance

You can import the default provider instance `elevenlabs` from `@ai-sdk/elevenlabs`:

```ts
import { elevenlabs } from '@ai-sdk/elevenlabs';
```

If you need a customized setup, you can import `createElevenLabs` from `@ai-sdk/elevenlabs` and create a provider instance with your settings:

```ts
import { createElevenLabs } from '@ai-sdk/elevenlabs';

const elevenlabs = createElevenLabs({
  // custom settings, e.g.
  fetch: customFetch,
});
```

You can use the following optional settings to customize the ElevenLabs provider instance:

* **apiKey** *string*

  API key that is being sent using the `Authorization` header.
  It defaults to the `ELEVENLABS_API_KEY` environment variable.

* **headers** *Record\<string,string>*

  Custom headers to include in the requests.

* **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\<Response>*

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
  Defaults to the global `fetch` function.
  You can use it as a middleware to intercept requests,
  or to provide a custom fetch implementation for e.g. testing.

## Transcription Models

You can create models that call the [ElevenLabs transcription API](https://elevenlabs.io/speech-to-text)
using the `.transcription()` factory method.

The first argument is the model id e.g. `scribe_v2`.

```ts
const model = elevenlabs.transcription('scribe_v2');
```

You can also pass additional provider-specific options using the `providerOptions` argument. For example, supplying the input language in ISO-639-1 (e.g. `en`) format can sometimes improve transcription performance if known beforehand.

```ts {7}
import { elevenlabs } from '@ai-sdk/elevenlabs';
import { experimental_transcribe as transcribe } from 'ai';

const result = await transcribe({
  model: elevenlabs.transcription('scribe_v2'),
  audio: new Uint8Array([1, 2, 3, 4]),
  providerOptions: { elevenlabs: { languageCode: 'en' } },
});
```

The following provider options are available:

* **languageCode** *string*

  An ISO-639-1 or ISO-639-3 language code corresponding to the language of the audio file.
  Can sometimes improve transcription performance if known beforehand.
  Defaults to `null`, in which case the language is predicted automatically.

* **tagAudioEvents** *boolean*

  Whether to tag audio events like (laughter), (footsteps), etc. in the transcription.
  Defaults to `true`.

* **numSpeakers** *integer*

  The maximum amount of speakers talking in the uploaded file.
  Can help with predicting who speaks when.
  The maximum amount of speakers that can be predicted is 32.
  Defaults to `null`, in which case the amount of speakers is set to the maximum value the model supports.

* **timestampsGranularity** *enum*

  The granularity of the timestamps in the transcription.
  Defaults to `'word'`.
  Allowed values: `'none'`, `'word'`, `'character'`.

* **diarize** *boolean*

  Whether to annotate which speaker is currently talking in the uploaded file.
  Defaults to `true`.

* **fileFormat** *enum*

  The format of input audio.
  Defaults to `'other'`.
  Allowed values: `'pcm_s16le_16'`, `'other'`.
  For `'pcm_s16le_16'`, the input audio must be 16-bit PCM at a 16kHz sample rate, single channel (mono), and little-endian byte order.
  Latency will be lower than with passing an encoded waveform.


# Client-side streaming

> Learn how to transcribe audio with ElevenLabs in realtime on the client side

## Overview

The ElevenLabs Realtime Speech to Text API enables you to transcribe audio streams in real-time with ultra-low latency using the Scribe Realtime v2 model. Whether you're building voice assistants, transcription services, or any application requiring live speech recognition, this WebSocket-based API delivers partial transcripts as you speak and committed transcripts when speech segments are complete.

Scribe v2 Realtime can be implemented on the client side to transcribe audio in realtime, either via the microphone or manually chunking the audio.

The client side implementation differs from server side in a few ways:

* Requires a single use token - this is a temporary token that can be used to connect to the API without exposing your API key.
* Audio from the microphone can be piped directly to the API to transcribe, without the need to manually chunk the audio.

For streaming audio from a URL, see the [Server-side streaming](/docs/developer-guides/cookbooks/speech-to-text/server-side-streaming) guide.

## Quickstart

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    <CodeBlocks>
      ```bash title="React"
      npm install @elevenlabs/react @elevenlabs/elevenlabs-js
      ```

      ```bash title="JavaScript"
      npm install @elevenlabs/client @elevenlabs/elevenlabs-js
      ```
    </CodeBlocks>
  </Step>

  <Step title="Create a token">
    To use the client side SDK, you need to create a single use token. This is a temporary token that can be used to connect to the API without exposing your API key. This can be done via the ElevenLabs API on the server side.

    <Warning>
      Never expose your API key to the client.
    </Warning>

    ```typescript
    // Node.js server
    import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

    const elevenlabs = new ElevenLabsClient({
      apiKey: process.env.ELEVENLABS_API_KEY,
    });

    app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
      const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

      res.json(token);
    });
    ```

    <Info>
      A single use token automatically expires after 15 minutes.
    </Info>
  </Step>

  <Step title="Start the transcribing session">
    Transcription can be done either via the microphone or manually chunking your own audio. Your own audio can be a file or a stream.

    <Info>
      For a full list of parameters and options the API supports, please refer to the [API reference](/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime).
    </Info>

    <Tabs>
      <Tab title="Microphone">
        <CodeBlocks>
          ```typescript title="React"
          import { useScribe } from "@elevenlabs/react";

          function MyComponent() {
            const scribe = useScribe({
              modelId: "scribe_v2_realtime",
              onPartialTranscript: (data) => {
                console.log("Partial:", data.text);
              },
              onCommittedTranscript: (data) => {
                console.log("Committed:", data.text);
              },
              onCommittedTranscriptWithTimestamps: (data) => {
                console.log("Committed with timestamps:", data.text);
                console.log("Timestamps:", data.words);
              },
            });

            const handleStart = async () => {
              // Fetch a single use token from the server
              const token = await fetchTokenFromServer();

              await scribe.connect({
                token,
                microphone: {
                  echoCancellation: true,
                  noiseSuppression: true,
                },
              });
            };

            return (
              <div>
                <button onClick={handleStart} disabled={scribe.isConnected}>
                  Start Recording
                </button>
                <button onClick={scribe.disconnect} disabled={!scribe.isConnected}>
                  Stop
                </button>

                {scribe.partialTranscript && <p>Live: {scribe.partialTranscript}</p>}

                <div>
                  {scribe.committedTranscripts.map((t) => (
                    <p key={t.id}>{t.text}</p>
                  ))}
                </div>
              </div>
            );
          }
          ```

          ```typescript title="JavaScript"
          // Client side
          import { Scribe, RealtimeEvents } from "@elevenlabs/client";

          // Ensure you have authentication headers set up
          const response = await fetch("/scribe-token", yourAuthHeaders);
          const { token } = await response.json();

          const connection = Scribe.connect({
            token,
            modelId: "scribe_v2_realtime",
            includeTimestamps: true,
            microphone: {
              echoCancellation: true,
              noiseSuppression: true,
              autoGainControl: true,
            },
          });

          // Set up event handlers

          // Session started
          connection.on(RealtimeEvents.SESSION_STARTED, () => {
            console.log("Session started");
          });

          // Partial transcripts (interim results), use this in your UI to show the live transcript
          connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
            console.log("Partial:", data.text);
          });

          // Committed transcripts
          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
            console.log("Committed:", data.text);
          });

          // Committed transcripts with word-level timestamps. Only received when includeTimestamps is set to true.
          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, (data) => {
            console.log("Committed:", data.text);
            console.log("Timestamps:", data.words);
          });

          // Errors - will catch all errors, both server and websocket specific errors
          connection.on(RealtimeEvents.ERROR, (error) => {
            console.error("Error:", error);
          });

          // Connection opened
          connection.on(RealtimeEvents.OPEN, () => {
            console.log("Connection opened");
          });

          // Connection closed
          connection.on(RealtimeEvents.CLOSE, () => {
            console.log("Connection closed");
          });

          // When you are done, close the connection
          connection.close();
          ```
        </CodeBlocks>
      </Tab>

      <Tab title="Manual audio chunking">
        <CodeBlocks>
          ```typescript title="React"
          import { useScribe, AudioFormat } from "@elevenlabs/react";

          function FileTranscription() {
            const [file, setFile] = useState<File | null>(null);
            const scribe = useScribe({
              modelId: "scribe_v2_realtime",
              audioFormat: AudioFormat.PCM_16000,
              sampleRate: 16000,
            });

            const transcribeFile = async () => {
              if (!file) return;

              // Fetch a single use token from the server
              const token = await fetchToken();
              await scribe.connect({ token });

              // Decode audio file
              const arrayBuffer = await file.arrayBuffer();
              const audioContext = new AudioContext({ sampleRate: 16000 });
              const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

              // Convert to PCM16
              const channelData = audioBuffer.getChannelData(0);
              const pcmData = new Int16Array(channelData.length);

              for (let i = 0; i < channelData.length; i++) {
                const sample = Math.max(-1, Math.min(1, channelData[i]));
                pcmData[i] = sample < 0 ? sample * 32768 : sample * 32767;
              }

              // Send in chunks
              const chunkSize = 4096;
              for (let offset = 0; offset < pcmData.length; offset += chunkSize) {
                const chunk = pcmData.slice(offset, offset + chunkSize);
                const bytes = new Uint8Array(chunk.buffer);
                const base64 = btoa(String.fromCharCode(...bytes));

                scribe.sendAudio(base64);
                await new Promise((resolve) => setTimeout(resolve, 50));
              }

              // Commit transcription
              scribe.commit();
            };

            return (
              <div>
                <input
                  type="file"
                  accept="audio/*"
                  onChange={(e) => setFile(e.target.files?.[0] || null)}
                />
                <button onClick={transcribeFile} disabled={!file || scribe.isConnected}>
                  Transcribe
                </button>

                {scribe.committedTranscripts.map((transcript) => (
                  <div key={transcript.id}>{transcript.text}</div>
                ))}
              </div>
            );
          }
          ```

          ```typescript title="JavaScript"
          import { Scribe, AudioFormat, RealtimeEvents, CommitStrategy } from "@elevenlabs/client";

          // Ensure you have authentication headers set up
          const response = await fetch("/scribe-token", yourAuthHeaders);
          const { token } = await response.json();

          const connection = Scribe.connect({
            token,
            modelId: "scribe_v2_realtime",
            includeTimestamps: true,
            audioFormat: AudioFormat.PCM_16000,
            sampleRate: 16000,
            commitStrategy: CommitStrategy.MANUAL,
          });

          // Set up event handlers
          connection.on(RealtimeEvents.SESSION_STARTED, () => {
            console.log("Session started");
            sendAudio();
          });

          connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
            console.log("Partial:", data.text);
          });

          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
            console.log("Committed:", data.text);
          });

          connection.on(RealtimeEvents.ERROR, (error) => {
            console.error("Error:", error);
          });

          // Committed transcripts with word-level timestamps. Only received when includeTimestamps is set to true.
          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, (data) => {
            console.log("Committed:", data.text);
            console.log("Timestamps:", data.words);

            // Committed transcript received, close the connection
            connection.close();
          });

          async function sendAudio() {
            // Get file from input element
            const fileInput = document.querySelector('input[type="file"]');
            const audioFile = fileInput.files[0];

            // Read file as ArrayBuffer
            const arrayBuffer = await audioFile.arrayBuffer();
            const audioData = new Uint8Array(arrayBuffer);

            // Convert to base64 and send in chunks
            const chunkSize = 8192; // 8KB chunks
            for (let i = 0; i < audioData.length; i += chunkSize) {
              const chunk = audioData.slice(i, i + chunkSize);
              const base64 = btoa(String.fromCharCode(...chunk));

              // Send audio chunk
              connection.send({ audioBase64: base64 });

              // Optional: Add delay to simulate real-time streaming
              await new Promise((resolve) => setTimeout(resolve, 100));
            }

            // Signal end of audio segment
            connection.commit();
          }
          ```
        </CodeBlocks>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Next steps

Learn how to handle transcripts and commit strategies in the [Transcripts and commit strategies](/docs/developer-guides/cookbooks/speech-to-text/realtime/transcripts-and-commit-strategies) section, and review the list of events and error types that can be received from the Realtime Speech to Text API in the [Event reference](/docs/developer-guides/cookbooks/speech-to-text/realtime/event-reference) section.


# Server-side streaming

> Learn how to transcribe audio with ElevenLabs in realtime on the server side

## Overview

The ElevenLabs Realtime Speech to Text API enables you to transcribe audio streams in real-time with ultra-low latency using the Scribe Realtime v2 model. Whether you're building voice assistants, transcription services, or any application requiring live speech recognition, this WebSocket-based API delivers partial transcripts as you speak and committed transcripts when speech segments are complete.

Scribe v2 Realtime can be implemented on the server side to transcribe audio in realtime, either via a URL, file or your own audio stream.

The server side implementation differs from client side in a few ways:

* Uses an ElevenLabs API key instead of a single use token.
* Supports streaming from a URL directly, without the need to manually chunk the audio.

For streaming audio directly from the microphone, see the [Client-side streaming](/docs/developer-guides/cookbooks/speech-to-text/client-side-streaming) guide.

## Quickstart

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Configure the SDK">
    The SDK provides two ways to transcribe audio in realtime: streaming from a URL or manually chunking the audio from either a file or your own audio stream.

    <Info>
      For a full list of parameters and options the API supports, please refer to the [API reference](/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime).
    </Info>

    <Tabs>
      <Tab title="Stream from URL">
        This example shows how to stream an audio file from a URL using the official SDK.

        <Warning>
          The `ffmpeg` tool is required when streaming from an URL. Visit [their website](https://ffmpeg.org/download.html) for installation instructions.
        </Warning>

        Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

        <CodeBlocks>
          ```python
          from dotenv import load_dotenv
          import os
          import asyncio
          from elevenlabs import ElevenLabs, RealtimeEvents, RealtimeUrlOptions

          load_dotenv()

          async def main():
              elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

              # Create an event to signal when to stop
              stop_event = asyncio.Event()

              # Connect to a streaming audio URL
              connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
                  model_id="scribe_v2_realtime",
                  url="https://npr-ice.streamguys1.com/live.mp3",
                  include_timestamps=True,
              ))

              # Set up event handlers
              def on_session_started(data):
                  print(f"Session started: {data}")

              def on_partial_transcript(data):
                  print(f"Partial: {data.get('text', '')}")

              def on_committed_transcript(data):
                  print(f"Committed: {data.get('text', '')}")

              # Committed transcripts with word-level timestamps. Only received when include_timestamps is set to True.
              def on_committed_transcript_with_timestamps(data):
                  print(f"Committed with timestamps: {data.get('words', '')}")

              # Errors - will catch all errors, both server and websocket specific errors
              def on_error(error):
                  print(f"Error: {error}")
                  # Signal to stop on error
                  stop_event.set()

              def on_close():
                  print("Connection closed")

              # Register event handlers
              connection.on(RealtimeEvents.SESSION_STARTED, on_session_started)
              connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, on_partial_transcript)
              connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, on_committed_transcript)
              connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, on_committed_transcript_with_timestamps)
              connection.on(RealtimeEvents.ERROR, on_error)
              connection.on(RealtimeEvents.CLOSE, on_close)

              print("Transcribing audio stream... (Press Ctrl+C to stop)")

              try:
                  # Wait until error occurs or connection closes
                  await stop_event.wait()
              except KeyboardInterrupt:
                  print("\nStopping transcription...")
              finally:
                  await connection.close()

          if __name__ == "__main__":
              asyncio.run(main())
          ```

          ```typescript
          import "dotenv/config";
          import { ElevenLabsClient, RealtimeEvents } from "@elevenlabs/elevenlabs-js";

          const elevenlabs = new ElevenLabsClient();

          const connection = await elevenlabs.speechToText.realtime.connect({
            modelId: "scribe_v2_realtime",
            url: "https://npr-ice.streamguys1.com/live.mp3",
            includeTimestamps: true,
          });

          connection.on(RealtimeEvents.SESSION_STARTED, (data) => {
            console.log("Session started", data);
          });

          connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (transcript) => {
            console.log("Partial transcript", transcript);
          });

          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (transcript) => {
            console.log("Committed transcript", transcript);
          });

          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, (transcript) => {
            console.log("Committed with timestamps", transcript);
          });

          connection.on(RealtimeEvents.ERROR, (error) => {
            console.log("Error", error);
          });

          connection.on(RealtimeEvents.CLOSE, () => {
            console.log("Connection closed");
          });

          ```
        </CodeBlocks>
      </Tab>

      <Tab title="Manual audio chunking">
        The easiest way to transcribe audio using Scribe is to use the official SDK. In case you aren't able to use the SDK, you can use the WebSocket API directly. See the WebSocket example below on how to use the WebSocket API.

        This example simulates a realtime transcription of an audio file.

        <CodeBlocks>
          ```python
          import asyncio
          import base64
          import os
          from dotenv import load_dotenv
          from pathlib import Path
          from elevenlabs import AudioFormat, CommitStrategy, ElevenLabs, RealtimeEvents, RealtimeAudioOptions
          from pydub import AudioSegment
          import sys

          load_dotenv()

          async def main():
              # Initialize the ElevenLabs client
              elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

              # Create an event to signal when transcription is complete
              transcription_complete = asyncio.Event()

              # Connect with manual audio chunk mode
              connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeAudioOptions(
                  model_id="scribe_v2_realtime",
                  audio_format=AudioFormat.PCM_16000,
                  sample_rate=16000,
                  commit_strategy=CommitStrategy.MANUAL,
                  include_timestamps=True,
              ))

              # Set up event handlers
              def on_session_started(data):
                  print(f"Session started: {data}")
                  # Start sending audio once session is ready
                  asyncio.create_task(send_audio())

              def on_partial_transcript(data):
                  transcript = data.get('text', '')
                  if transcript:
                      print(f"Partial: {transcript}")

              def on_committed_transcript(data):
                  transcript = data.get('text', '')
                  print(f"\nCommitted transcript: {transcript}")

              def on_committed_transcript_with_timestamps(data):
                  print(f"Timestamps: {data.get('words', '')}")
                  print("-" * 50)
                  # Signal that transcription is complete
                  transcription_complete.set()

              def on_error(error):
                  print(f"Error: {error}")
                  transcription_complete.set()

              def on_close():
                  print("Connection closed")
                  transcription_complete.set()

              # Register event handlers
              connection.on(RealtimeEvents.SESSION_STARTED, on_session_started)
              connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, on_partial_transcript)
              connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, on_committed_transcript)
              connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, on_committed_transcript_with_timestamps)
              connection.on(RealtimeEvents.ERROR, on_error)
              connection.on(RealtimeEvents.CLOSE, on_close)

              # Convert audio file to PCM format if necessary
              def load_and_convert_audio(audio_path: str | Path, target_sample_rate: int = 16000) -> bytes:
                  try:
                      if str(audio_path).lower().endswith('.pcm'):
                          with open(audio_path, 'rb') as f:
                              return f.read()

                      audio = AudioSegment.from_file(audio_path)
                      if audio.channels > 1:
                          audio = audio.set_channels(1)
                      if audio.frame_rate != target_sample_rate:
                          audio = audio.set_frame_rate(target_sample_rate)
                      audio = audio.set_sample_width(2)
                      return audio.raw_data
                  except Exception as e:
                      print(f"Error loading audio: {e}")
                      sys.exit(1)

              async def send_audio():
                  """Send audio chunks from an audio file"""
                  audio_file_path = Path("/path/to/audio.mp3")

                  try:
                      # Read the audio file
                      audio_data = load_and_convert_audio(audio_file_path)

                      # Split into chunks (1 second of audio = 32000 bytes at 16kHz, 16-bit)
                      chunk_size = 32000
                      chunks = [audio_data[i:i + chunk_size] for i in range(0, len(audio_data), chunk_size)]

                      # Send each chunk
                      for i, chunk in enumerate(chunks):
                          chunk_base64 = base64.b64encode(chunk).decode('utf-8')
                          await connection.send({"audio_base_64": chunk_base64, "sample_rate": 16000})

                          # Wait 1 second between chunks (simulating real-time)
                          if i < len(chunks) - 1:
                              await asyncio.sleep(1)

                      # Small delay before committing to let last chunk process
                      await asyncio.sleep(0.5)

                      # Commit to finalize segment and get committed transcript
                      await connection.commit()

                  except Exception as e:
                      print(f"Error sending audio: {e}")
                      transcription_complete.set()

              try:
                  # Wait for transcription to complete
                  await transcription_complete.wait()
              except KeyboardInterrupt:
                  print("\nStopping...")
              finally:
                  await connection.close()

          if __name__ == "__main__":
              asyncio.run(main())

          ```

          ```typescript
          import "dotenv/config";
          import * as fs from "node:fs";
          import { ElevenLabsClient, RealtimeEvents, AudioFormat } from "@elevenlabs/elevenlabs-js";

          const elevenlabs = new ElevenLabsClient();

          const connection = await elevenlabs.speechToText.realtime.connect({
            modelId: "scribe_v2_realtime",
            audioFormat: AudioFormat.PCM_16000,
            sampleRate: 16000,
            includeTimestamps: true,
          });

          connection.on(RealtimeEvents.SESSION_STARTED, (data) => {
            console.log("Session started", data);
            sendAudio();
          });

          connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (transcript) => {
            console.log("Partial transcript", transcript);
          });

          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (transcript) => {
            console.log("Committed transcript", transcript);
          });

          connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS, (transcript) => {
            console.log("Committed with timestamps", transcript);
          });

          connection.on(RealtimeEvents.ERROR, (error) => {
            console.log("Error", error);
          });

          connection.on(RealtimeEvents.CLOSE, () => {
            console.log("Connection closed");
          });

          async function sendAudio() {
            const pcmFilePath = "/path/to/audio.pcm";

            const chunkSize = 32000; // 1 second of 16kHz audio (16000 samples * 2 bytes per sample)

            // Read the entire file into a buffer
            const audioBuffer = fs.readFileSync(pcmFilePath);

            // Split the buffer into chunks of exactly chunkSize bytes
            const chunks: Buffer[] = [];
            for (let i = 0; i < audioBuffer.length; i += chunkSize) {
              const chunk = audioBuffer.subarray(i, i + chunkSize);
              chunks.push(chunk);
            }

            // Send each chunk via websocket payload
            for (let i = 0; i < chunks.length; i++) {
              const chunk = chunks[i];
              const chunkBase64 = chunk.toString("base64");

              connection.send({
                audioBase64: chunkBase64,
                sampleRate: 16000,
              });

              // Wait 1 second between chunks to simulate real-time streaming
              // (each chunk contains 1 second of audio at 16kHz)
              if (i < chunks.length - 1) {
                await new Promise(resolve => setTimeout(resolve, 1000));
              }
            }

            // Small delay before final commit to let the last chunk process
            await new Promise(resolve => setTimeout(resolve, 500));

            // send final commit
            connection.commit();
          }
          ```

          ```python title="Python WebSocket example"
          # Use this example if you are unable to use the SDK
          import asyncio
          import base64
          import json
          import websockets
          from dotenv import load_dotenv
          import os

          load_dotenv()

          async def send_audio(ws, audio_data):
              """Send audio chunks to the websocket"""
              chunk_size = 32000  # 1 second of 16kHz audio

              for i in range(0, len(audio_data), chunk_size):
                  chunk = audio_data[i : i + chunk_size]
                  await ws.send(
                      json.dumps(
                          {
                              "message_type": "input_audio_chunk",
                              "audio_base_64": base64.b64encode(chunk).decode(),
                              "commit": False,
                              "sample_rate": 16000,
                          }
                      )
                  )
                  # Wait 1 second between chunks to simulate real-time streaming
                  await asyncio.sleep(1)

              # Small delay before final commit
              await asyncio.sleep(0.5)

              # Send final commit
              await ws.send(
                  json.dumps(
                      {
                          "message_type": "input_audio_chunk",
                          "audio_base_64": "",
                          "commit": True,
                          "sample_rate": 16000,
                      }
                  )
              )

          async def receive_transcripts(ws):
              """Receive and process transcripts from the websocket"""
              while True:
                  try:
                      # Wait for 10 seconds for a message
                      # Adjust the timeout in cases where audio files have more than 10 seconds before speech starts, or if the audio is longer than 10 seconds.
                      message = await asyncio.wait_for(ws.recv(), timeout=10.0)
                      data = json.loads(message)

                      if data["message_type"] == "partial_transcript":
                          print(f"Partial: {data['text']}")
                      elif data["message_type"] == "committed_transcript":
                          print(f"Committed: {data['text']}")
                      elif data["message_type"] == "committed_transcript_with_timestamps":
                          print(f"Committed with timestamps: {data['words']}")
                          break
                      elif data["message_type"] == "input_error":
                          print(f"Error: {data}")
                  except asyncio.TimeoutError:
                      print("Timeout waiting for transcript")


          async def transcribe():
              url = "wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime"
              headers = {"xi-api-key": os.getenv("ELEVENLABS_API_KEY")}

              async with websockets.connect(url, additional_headers=headers) as ws:
                  # Connection established, wait for session_started
                  session_msg = await ws.recv()
                  print(f"Session started: {session_msg}")

                  # Read audio file (16 kHz, mono, 16-bit PCM, little-endian)
                  with open("/path/to/audio.pcm", "rb") as f:
                      audio_data = f.read()

                  # Run sending and receiving concurrently
                  await asyncio.gather(
                      send_audio(ws, audio_data),
                      receive_transcripts(ws)
                  )


          asyncio.run(transcribe())
          ```

          ```typescript title="TypeScript WebSocket example"
              // Use this example if you are unable to use the SDK
              import "dotenv/config";
              import * as fs from "node:fs";
              // Make sure to install the "ws" library beforehand
              import WebSocket from "ws";

              const uri = "wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime";
              const websocket = new WebSocket(uri, {
                headers: {
                  "xi-api-key": process.env.ELEVENLABS_API_KEY,
                },
              });

              websocket.on("open", async () => {
                console.log("WebSocket opened");
              });

              // Listen to the incoming message from the websocket connection
              websocket.on("message", function incoming(event) {
                const data = JSON.parse(event.toString());

                switch (data.message_type) {
                  case "session_started":
                    console.log("Session started", data);
                    sendAudio();
                    break;
                  case "partial_transcript":
                    console.log("Partial:", data);
                    break;
                  case "committed_transcript":
                    console.log("Committed:", data);
                    break;
                  // Committed transcripts with word-level timestamps. Only received when "include_timestamps=true" is included in the query parameters
                  case "committed_transcript_with_timestamps":
                    console.log("Committed with timestamps:", data);
                    websocket.close();
                    break;
                  default:
                    console.log(data);
                    break;
                }

              });

              async function sendAudio() {
                // 16 kHz, mono, 16-bit PCM, little-endian
                const pcmFilePath = "/path/to/audio.pcm";

                const chunkSize = 32000; // 1 second of 16kHz audio (16000 samples * 2 bytes per sample)

                // Read the entire file into a buffer
                const audioBuffer = fs.readFileSync(pcmFilePath);

                // Split the buffer into chunks of exactly chunkSize bytes
                const chunks: Buffer[] = [];
                for (let i = 0; i < audioBuffer.length; i += chunkSize) {
                  const chunk = audioBuffer.subarray(i, i + chunkSize);
                  chunks.push(chunk);
                }

                // Send each chunk via websocket payload
                for (let i = 0; i < chunks.length; i++) {
                  const chunk = chunks[i];
                  const chunkBase64 = chunk.toString("base64");

                  websocket.send(JSON.stringify({
                    message_type: "input_audio_chunk",
                    audio_base_64: chunkBase64,
                    commit: false,
                    sample_rate: 16000,
                  }));

                  // Wait 1 second between chunks to simulate real-time streaming
                  // (each chunk contains 1 second of audio at 16kHz)
                  if (i < chunks.length - 1) {
                    await new Promise(resolve => setTimeout(resolve, 1000));
                  }
                }

                // Small delay before final commit to let the last chunk process
                await new Promise(resolve => setTimeout(resolve, 500));

                // send final commit
                websocket.send(JSON.stringify({
                  message_type: "input_audio_chunk",
                  audio_base_64: "",
                  commit: true,
                  sample_rate: 16000,
                }));
              }
          ```
        </CodeBlocks>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You will see the transcription of the audio file printed to the console in partial and committed transcripts.
  </Step>
</Steps>

## Next steps

Learn how to handle transcripts and commit strategies in the [Transcripts and commit strategies](/docs/developer-guides/cookbooks/speech-to-text/realtime-commit-strategies) section, and review the list of events and error types that can be received from the Realtime Speech to Text API in the [Event reference](/docs/developer-guides/cookbooks/speech-to-text/realtime-event-reference) section.


# Transcripts and commit strategies

> Learn how to handle transcripts and commit strategies with ElevenLabs in Realtime Speech to Text

## Overview

When transcribing audio, you will receive partial and committed transcripts.

* **Partial transcripts** - the interim results of the transcription
* **Committed transcripts** - the final results of the transcription segment that are sent when a "commit" message is received. A session can have multiple committed transcripts.

The commit transcript can optionally contain word-level timestamps. This is only received when the "include timestamps" option is set to `true`.

<CodeBlocks>
  ```python
  # Initialize the connection
  connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v2_realtime",
    include_timestamps=True, # Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
  ))
  ```

  ```typescript
  // Initialize the connection
  const connection = await elevenlabs.speechToText.realtime.connect({
    modelId: 'scribe_v2_realtime',
    includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
  });
  ```

  ```typescript title="React"
  const connection = useScribe({
    modelId: 'scribe_v2_realtime',
    // Configuring this callback will automatically set the `includeTimestamps` option to `true`
    onCommittedTranscriptWithTimestamps: (data) => {
      console.log('Committed with timestamps:', data.text);
      console.log('Timestamps:', data.words);
    },
  });
  ```

  ```typescript title="JavaScript"
  const connection = Scribe.connect({
    modelId: 'scribe_v2_realtime',
    includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
  });
  ```
</CodeBlocks>

## Commit strategies

When sending audio chunks via the WebSocket, transcript segments can be committed in two ways: Manual Commit or Voice Activity Detection (VAD).

### Manual commit

With the manual commit strategy, you control when to commit transcript segments. This is the strategy that is used by default. Committing a segment will clear the processed accumulated transcript and start a new segment without losing context. Committing every 20-30 seconds is good practice to improve latency. By default the stream will be automatically committed every 90 seconds.

For best results, commit during silence periods or another logical point like a turn model.

<Info>
  Transcript processing starts after the first 2 seconds of audio are sent.
</Info>

<CodeBlocks>
  ```python
  await connection.send({
    "audio_base_64": audio_base_64,
    "sample_rate": 16000,
  })

  # When ready to finalize the segment
  await connection.commit()
  ```

  ```typescript
  connection.send({
    audioBase64: audioBase64,
    sampleRate: 16000,
  });

  // When ready to finalize the segment
  connection.commit();
  ```
</CodeBlocks>

<Warning>
  Committing manually several times in a short sequence can degrade model performance.
</Warning>

#### Sending previous text context

When sending audio for transcription, you can send previous text context alongside the first audio chunk to help the model understand the context of the speech. This is useful in a few scenarios:

* Agent text for conversational AI use cases - Allows the model to more easily understand the context of the conversation and produce better transcriptions.
* Reconnection after a network error - This allows the model to continue transcribing, using the previous text as guidance.
* General contextual information - A short description of what the transcription will be about helps the model understand the context.

<Warning>
  Sending `previous_text` context is only possible when sending the first audio chunk via
  `connection.send()`. Sending it in subsequent chunks will result in an error. Previous text works
  best when it's under *50* characters long.
</Warning>

<CodeBlocks>
  ```python
  await connection.send({
    "audio_base_64": audio_base_64,
    "previous_text": "The previous text context",
  })
  ```

  ```typescript
  connection.send({
    audioBase64: audioBase64,
    previousText: 'The previous text context',
  });
  ```
</CodeBlocks>

### Voice Activity Detection (VAD)

With the VAD strategy, the transcription engine automatically detects speech and silence segments. When a silence threshold is reached, the transcription engine will commit the transcript segment automatically.

When transcribing audio from the microphone in the [client-side integration](/docs/developers/guides/cookbooks/speech-to-text/realtime/client-side-streaming), it is recommended to use the VAD strategy.

<CodeBlocks>
  ```typescript title="Client"
  import { Scribe, AudioFormat, CommitStrategy } from "@elevenlabs/client";

  const connection = Scribe.connect({
    token: "sutkn_1234567890",
    modelId: "scribe_v2_realtime",
    audioFormat: AudioFormat.PCM_16000,
    commitStrategy: CommitStrategy.VAD,
    vadSilenceThresholdSecs: 1.5,
    vadThreshold: 0.4,
    minSpeechDurationMs: 100,
    minSilenceDurationMs: 100,
  });
  ```

  ```python
  from dotenv import load_dotenv
  from elevenlabs import AudioFormat, CommitStrategy, ElevenLabs, RealtimeAudioOptions

  load_dotenv()

  elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

  connection = await elevenlabs.speech_to_text.realtime.connect(
      RealtimeAudioOptions(
          model_id="scribe_v2_realtime",
          audio_format=AudioFormat.PCM_16000,
          commit_strategy=CommitStrategy.VAD,
          vad_silence_threshold_secs=1.5,
          vad_threshold=0.4,
          min_speech_duration_ms=100,
          min_silence_duration_ms=100,
      )
  )
  ```

  ```typescript title="TypeScript"
  import { ElevenLabsClient, AudioFormat, CommitStrategy } from '@elevenlabs/elevenlabs-js';

  const elevenlabs = new ElevenLabsClient();

  const connection = await elevenlabs.speechToText.realtime.connect({
    modelId: "scribe_v2_realtime",
    audioFormat: AudioFormat.PCM_16000,
    commitStrategy: CommitStrategy.VAD,
    vadSilenceThresholdSecs: 1.5,
    vadThreshold: 0.4,
    minSpeechDurationMs: 100,
    minSilenceDurationMs: 100,
  });
  ```
</CodeBlocks>

## Supported audio formats

| Format     | Sample Rate | Description                             |
| ---------- | ----------- | --------------------------------------- |
| pcm\_8000  | 8 kHz       | 16-bit PCM, little-endian               |
| pcm\_16000 | 16 kHz      | 16-bit PCM, little-endian (recommended) |
| pcm\_22050 | 22.05 kHz   | 16-bit PCM, little-endian               |
| pcm\_24000 | 24 kHz      | 16-bit PCM, little-endian               |
| pcm\_44100 | 44.1 kHz    | 16-bit PCM, little-endian               |
| pcm\_48000 | 48 kHz      | 16-bit PCM, little-endian               |
| ulaw\_8000 | 8 kHz       | 8-bit μ-law encoding                    |

## Best practices

### Audio quality

* For best results, use a 16kHz sample rate for an optimum balance of quality and bandwidth.
* Ensure clean audio input with minimal background noise.
* Use an appropriate microphone gain to avoid clipping.
* Only mono audio is supported at this time.

### Chunk size

* Send audio chunks of 0.1 - 1 second in length for smooth streaming.
* Smaller chunks result in lower latency but more overhead.
* Larger chunks are more efficient but can introduce latency.


# Realtime event reference

> Reference of the events received from the Realtime Speech to Text API

Review the API reference for the [Realtime Speech to Text API](/docs/api-reference/speech-to-text/v-1-speech-to-text-realtime) for more information on the API and its options.

## Sent events

| Event               | Description                       | When to use                        |
| ------------------- | --------------------------------- | ---------------------------------- |
| `input_audio_chunk` | Send audio data for transcription | Continuously while streaming audio |

## Received events

| Event                                  | Description                                                                              | When received                                                                                                                              |
| -------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `session_started`                      | Confirms connection and returns session configuration                                    | Immediately after WebSocket connection is established                                                                                      |
| `partial_transcript`                   | Live transcript update                                                                   | During audio processing, before a commit is made                                                                                           |
| `committed_transcript`                 | Transcript of the audio segment                                                          | After a commit (either manual or VAD triggered)                                                                                            |
| `committed_transcript_with_timestamps` | Sent after the committed transcript of the audio segment. Contains word-level timestamps | Sent after the committed transcript of the audio segment. Only received when `include_timestamps=true` is included in the query parameters |

## Error handling

If an error occurs, an error message will be returned before the WebSocket connection is closed.

| Error Type                    | Description                                                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `auth_error`                  | An error occurred while authenticating the request. Double check your API key                                                        |
| `quota_exceeded`              | You have exceeded your usage quota                                                                                                   |
| `transcriber_error`           | An error occurred while transcribing the audio.                                                                                      |
| `input_error`                 | An error occurred while processing the audio chunk. Likely due to invalid input format or parameters                                 |
| `error`                       | A generic server error                                                                                                               |
| `commit_throttled`            | The commit was throttled due to too many commit requests made in a short period of time                                              |
| `transcriber_error`           | An error occurred while transcribing the audio.                                                                                      |
| `unaccepted_terms`            | You haven't accepted the terms of service to use Scribe. Please review and accept the terms & conditions in the ElevenLabs dashboard |
| `rate_limited`                | You are rate limited. Please reduce the amount of requests made in a short period of time                                            |
| `queue_overflow`              | The processing queue is full. Please send fewer requests made in a short period of time                                              |
| `resource_exhausted`          | Server resources are at capacity. Please try again later                                                                             |
| `session_time_limit_exceeded` | Maximum session time has been reached. Please start a new session or upgrade your subscription                                       |
| `chunk_size_exceeded`         | The audio chunk size is too large. Please reduce the chunk size                                                                      |
| `insufficient_audio_activity` | You haven't sent enough audio activity to maintain the connection                                                                    |


# Music quickstart

> Learn how to generate music with Eleven Music.

This guide will show you how to generate music with Eleven Music.

<Info>
  The Eleven Music API is only available to paid users.
</Info>

## Using the Eleven Music API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python
      # example.py
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import os
      from dotenv import load_dotenv
      load_dotenv()

      elevenlabs = ElevenLabs(
          api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      track = elevenlabs.music.compose(
          prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
          music_length_ms=10000,
      )

      # Save the track to a file
      with open("path/to/music.mp3", "wb") as f:
          for chunk in track:
              f.write(chunk)
      ```

      ```typescript
      // example.mts
      import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
      import { Readable } from "stream";
      import { createWriteStream } from "fs";
      import { pipeline } from "stream/promises";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const track = await elevenlabs.music.compose({
        prompt: "Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
        musicLengthMs: 10000,
      });

      // Save the track to a file
      await pipeline(Readable.from(track), createWriteStream("path/to/music.mp3"));
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the generated music playing.
  </Step>
</Steps>

## Composition plans

A composition plan is a JSON object that describes the music you want to generate in finer detail. It can then be used to generate music with Eleven Music.

Using a plan is optional, but it can be used to generate more complex music by giving you more granular control over each section of the generation.

### Generating a composition plan

A composition plan can be generated from a prompt by using the API.

<CodeBlocks>
  ```python
  from elevenlabs.client import ElevenLabs
  from elevenlabs.play import play
  import os
  from dotenv import load_dotenv
  load_dotenv()

  elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
  )

  composition_plan = elevenlabs.music.composition_plan.create(
      prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
      music_length_ms=10000,
  )

  print(composition_plan)
  ```

  ```typescript
  import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
  import "dotenv/config";

  const elevenlabs = new ElevenLabsClient();

  const compositionPlan = await elevenlabs.music.compositionPlan.create({
    prompt: "Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    musicLengthMs: 10000,
  });

  console.log(JSON.stringify(compositionPlan, null, 2));
  ```
</CodeBlocks>

The above will generate a composition plan similar to the following:

```json
{
  "positiveGlobalStyles": [
    "electronic",
    "fast-paced",
    "driving synth arpeggios",
    "punchy drums",
    "distorted bass",
    "glitch effects",
    "aggressive rhythmic textures",
    "high adrenaline"
  ],
  "negativeGlobalStyles": ["acoustic", "slow", "minimalist", "ambient", "lo-fi"],
  "sections": [
    {
      "sectionName": "Intro",
      "positiveLocalStyles": [
        "rising synth arpeggio",
        "glitch fx",
        "filtered noise sweep",
        "soft punchy kick building tension"
      ],
      "negativeLocalStyles": ["soft pads", "melodic vocals", "ambient textures"],
      "durationMs": 3000,
      "lines": []
    },
    {
      "sectionName": "Peak Drop",
      "positiveLocalStyles": [
        "full punchy drums",
        "distorted bass stab",
        "aggressive rhythmic hits",
        "rapid arpeggio sequences"
      ],
      "negativeLocalStyles": ["smooth transitions", "clean bass", "slow buildup"],
      "durationMs": 4000,
      "lines": []
    },
    {
      "sectionName": "Final Burst",
      "positiveLocalStyles": [
        "glitch stutter",
        "energy burst vox chopped sample",
        "quick transitions",
        "snare rolls"
      ],
      "negativeLocalStyles": ["long reverb tails", "fadeout", "gentle melodies"],
      "durationMs": 3000,
      "lines": []
    }
  ]
}
```

### Using a composition plan

A composition plan can be used to generate music by passing it to the `compose` method.

<CodeBlocks>
  ```python
  # You can pass in composition_plan or prompt, but not both.
  composition = elevenlabs.music.compose(
      composition_plan=composition_plan,
  )

  play(composition)
  ```

  ```typescript
  // You can pass in compositionPlan or prompt, but not both.
  const composition = await elevenlabs.music.compose({
      compositionPlan,
  });

  await play(composition);
  ```
</CodeBlocks>

## Generating music with details

For each music generation a composition plan is created from the prompt. You can opt to retrieve this plan by using the detailed response endpoint.

<CodeBlocks>
  ```python
  track_details = elevenlabs.music.compose_detailed(
      prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
      music_length_ms=10000,
  )

  print(track_details.json) # json contains composition_plan and song_metadata. The composition plan will include lyrics (if applicable)
  print(track_details.filename)
  # track_details.audio contains the audio bytes
  ```

  ```typescript
  const trackDetails = await elevenlabs.music.composeDetailed({
    prompt: 'Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 30–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.',
    musicLengthMs: 10000,
  });

  console.log(JSON.stringify(trackDetails.json, null, 2)); // json contains composition_plan and song_metadata. The composition plan will include lyrics (if applicable)
  console.log(trackDetails.filename);
  // trackDetails.audio contains the audio bytes
  ```
</CodeBlocks>

## Copyrighted material

Attempting to generate music or a composition plan that contains copyrighted material will result in an error. This includes mentioning a band or musician by name or using copyrighted lyrics.

### Prompts with copyrighted material

In these cases, the API will return a `bad_prompt` error that contains a suggestion of what prompt you could use instead.

<CodeBlocks>
  ```python
  try:
      # This will result in a bad_prompt error
      track = elevenlabs.music.compose(
          prompt="A song that sounds like 'Bohemian Rhapsody'",
          music_length_ms=10000,
      )
    except Exception as e:
        if e.body['detail']['status'] == 'bad_prompt':
            prompt_suggestion = e.body['detail']['data']['prompt_suggestion']
            print(prompt_suggestion) # Prints: An epic rock ballad with dramatic tempo changes, operatic harmonies, and a narrative structure that blends melancholy with bursts of theatrical intensity.

            # Use the prompt suggestion to generate the track instead
  ```

  ```typescript
  try {
    // This will result in a bad_prompt error
    const track = await elevenlabs.music.compose({
      prompt: "A song that sounds like 'Bohemian Rhapsody'",
      musicLengthMs: 10000,
    });
  } catch (error) {
    if (error.body.detail.status === 'bad_prompt') {
      const promptSuggestion = error.body.detail.data.prompt_suggestion;
      console.log(promptSuggestion); // Logs: An epic rock ballad with dramatic tempo changes, operatic harmonies, and a narrative structure that blends melancholy with bursts of theatrical intensity.

      // Use the prompt suggestion to generate the track instead
    }
  }
  ```
</CodeBlocks>

### Composition plans with copyrighted material

If styles using copyrighted material are used when generating a composition plan, a `bad_composition_plan` error will be returned. Similar to music prompts, a suggested composition plan `composition_plan_suggestion` will be returned within the error.

<Warning>
  In the case of a composition plan or prompt that contains harmful material, no suggested prompt
  will be returned.
</Warning>

## Next steps

Explore the [API reference](/docs/api-reference/music/compose) for more information on the Music API and its options.


# Music streaming

> Learn how to stream music with Eleven Music.

This guide will show you how to stream music with Eleven Music.

<Info>
  The Eleven Music API is only available to paid users.
</Info>

## Using the Eleven Music API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python
      # example.py
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import os
      from io import BytesIO
      from dotenv import load_dotenv
      load_dotenv()

      elevenlabs = ElevenLabs(
          api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      stream = elevenlabs.music.stream(
          prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
          music_length_ms=10000,
      )

      # Create a BytesIO object to hold the audio data in memory
      audio_stream = BytesIO()

      # Write each chunk of audio data to the stream
      for chunk in stream:
          if chunk:
              audio_stream.write(chunk)

      # Reset stream position to the beginning
      audio_stream.seek(0)

      play(audio_stream)
      ```

      ```typescript
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const stream = await elevenlabs.music.stream({
        prompt: "Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
        musicLengthMs: 10000,
      });

      const chunks: Buffer[] = [];

      for await (const chunk of stream) {
          chunks.push(chunk);
      }

      const audioStream = Buffer.concat(chunks);

      await play(audioStream);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the generated music playing.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/music/stream) for more information on the Speech to Text API and its options.


# Text to Dialogue quickstart

> Learn how to generate immersive dialogue from text.

This guide will show you how to generate immersive, natural-sounding dialogue from text using the Text to Dialogue API.

## Using the Text to Dialogue API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio = elevenlabs.text_to_dialogue.convert(
          inputs=[
              {
                  "text": "[cheerfully] Hello, how are you?",
                  "voice_id": "9BWtsMINqrJLrRacOk9x",
              },
              {
                  "text": "[stuttering] I'm... I'm doing well, thank you",
                  "voice_id": "IKne3meq5aSn9XLyUdCD",
              }
          ]
      )

      play(audio)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const audio = await elevenlabs.textToDialogue.convert({
          inputs: [
              {
                  text: "[cheerfully] Hello, how are you?",
                  voiceId: "9BWtsMINqrJLrRacOk9x",
              },
              {
                  text: "[stuttering] I'm... I'm doing well, thank you",
                  voiceId: "IKne3meq5aSn9XLyUdCD",
              },
          ],
      });

      play(audio);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the dialogue audio play.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/text-to-dialogue/convert) for more information on the Text to Dialogue API and its options.


# Voice Changer quickstart

> Learn how to transform the voice of an audio file using the Voice Changer API.

This guide will show you how to transform the voice of an audio file using the Voice Changer API.

## Using the Voice Changer API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import requests
      from io import BytesIO

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )
      voice_id = "JBFqnCBsd6RMkjVDRZzb"

      audio_url = (
          "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      )
      response = requests.get(audio_url)
      audio_data = BytesIO(response.content)

      audio_stream = elevenlabs.speech_to_speech.convert(
          voice_id=voice_id,
          audio=audio_data,
          model_id="eleven_multilingual_sts_v2",
          output_format="mp3_44100_128",
      )

      play(audio_stream)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();
      const voiceId = "JBFqnCBsd6RMkjVDRZzb";

      const response = await fetch(
        "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      );
      const audioBlob = new Blob([await response.arrayBuffer()], { type: "audio/mp3" });

      const audioStream = await elevenlabs.speechToSpeech.convert(voiceId, {
        audio: audioBlob,
        modelId: "eleven_multilingual_sts_v2",
        outputFormat: "mp3_44100_128",
      });

      await play(audioStream);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the transformed voice playing through your speakers.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/speech-to-speech/convert) for more information on the Voice Changer API and its options.


# Voice Isolator quickstart

> Learn how to remove background noise from an audio file using the Voice Isolator API.

This guide will show you how to remove background noise from an audio file using the Voice Isolator API.

## Using the Voice Isolator API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import requests
      from io import BytesIO

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio_url = "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/fin.mp3"
      response = requests.get(audio_url)
      audio_data = BytesIO(response.content)

      audio_stream = elevenlabs.audio_isolation.convert(audio=audio_data)

      play(audio_stream)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const audioUrl =
        "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/fin.mp3";
      const response = await fetch(audioUrl);
      const audioBlob = new Blob([await response.arrayBuffer()], {
        type: "audio/mp3",
      });

      const audioStream = await elevenlabs.audioIsolation.convert({
        audio: audioBlob,
      });

      await play(audioStream);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the isolated voice playing through your speakers.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/audio-isolation/convert) for more information on the Voice Changer API and its options.


# Dubbing quickstart

> Learn how to dub audio and video files across languages using the Dubbing API.

This guide will show you how to dub an audio file across languages. In this example we'll dub an audio file from English to Spanish.

## Using the Dubbing API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import requests
      from io import BytesIO
      import time

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      target_lang = "es"  # Spanish

      audio_url = (
          "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      )
      response = requests.get(audio_url)

      audio_data = BytesIO(response.content)
      audio_data.name = "audio.mp3"

      # Start dubbing
      dubbed = elevenlabs.dubbing.create(
          file=audio_data, target_lang=target_lang
      )

      while True:
          status = elevenlabs.dubbing.get(dubbed.dubbing_id).status
          if status == "dubbed":
              dubbed_file = elevenlabs.dubbing.audio.get(dubbed.dubbing_id, target_lang)
              play(dubbed_file)
              break
          else:
              print("Audio is still being dubbed...")
              time.sleep(5)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const targetLang = "es"; // spanish
      const sourceAudio = await fetch(
        "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      );
      const audioBlob = new Blob([await sourceAudio.arrayBuffer()], {
        type: "audio/mp3",
      });

      // Start dubbing
      const dubbed = await elevenlabs.dubbing.create({
        file: audioBlob,
        targetLang: targetLang,
      });

      while (true) {
        const { status } = await elevenlabs.dubbing.get(
          dubbed.dubbingId
        );
        if (status === "dubbed") {
          const dubbedFile = await elevenlabs.dubbing.audio.get(
            dubbed.dubbingId,
            targetLang
          );
          await play(dubbedFile);
          break;
        } else {
          console.log("Audio is still being dubbed...");
        }

        // Wait 5 seconds between checks
        await new Promise((resolve) => setTimeout(resolve, 5000));
      }
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the dubbed audio file playing through your speakers.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/dubbing/create) for more information on the Dubbing API and its options.


# Sound Effects quickstart

> Learn how to generate sound effects using the Sound Effects API.

This guide will show you how to generate sound effects using the Sound Effects API.

## Using the Sound Effects API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )
      audio = elevenlabs.text_to_sound_effects.convert(text="Cinematic Braam, Horror")

      play(audio)
      ```

      ```typescript
      // example.mts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";

      const elevenlabs = new ElevenLabsClient();

      const audio = await elevenlabs.textToSoundEffects.convert({
        text: "Cinematic Braam, Horror",
      });

      await play(audio);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear your generated sound effect playing through your speakers.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/speech-to-text/convert) for more information on the Speech to Text API and its options.


# Instant Voice Cloning quickstart

> Learn how to clone a voice using the Clone Voice API.

This guide will show you how to create an Instant Voice Clone using the Clone Voice API. To create an Instant Voice Clone via the dashboard, refer to the [Instant Voice Clone](/docs/creative-platform/voices/voice-cloning/instant-voice-cloning) product guide.

For an outline of the differences between Instant Voice Clones and Professional Voice Clones, refer to the [Voices capability](/docs/overview/capabilities/voices) guide.

## Using the Instant Voice Clone API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlock>
      ```python maxLines=0
      # example.py
      import os
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from io import BytesIO

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      voice = elevenlabs.voices.ivc.create(
          name="My Voice Clone",
          # Replace with the paths to your audio files.
          # The more files you add, the better the clone will be.
          files=[BytesIO(open("/path/to/your/audio/file.mp3", "rb").read())]
      )

      print(voice.voice_id)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      import fs from "node:fs";

      const elevenlabs = new ElevenLabsClient();

      const voice = await elevenlabs.voices.ivc.create({
          name: "My Voice Clone",
          // Replace with the paths to your audio files.
          // The more files you add, the better the clone will be.
          files: [
              fs.createReadStream(
                  "/path/to/your/audio/file.mp3",
              ),
          ],
      });

      console.log(voice.voiceId);
      ```
    </CodeBlock>
  </Step>

  <Step title="Execute the code">
    <CodeBlock>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlock>

    You should see the voice ID printed to the console.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/voices/ivc/create) for more information on creating a voice clone.


# Professional Voice Cloning quickstart

> Learn how to create a Professional Voice Clone using the PVC API.

This guide will show you how to create a Professional Voice Clone (PVC) using the PVC API. To create a PVC via the dashboard, refer to the [Professional Voice Clone](/docs/creative-platform/voices/voice-cloning/professional-voice-cloning) product guide.

<Info>
  Creating a PVC requires you to be on the [Creator plan](https://elevenlabs.io/pricing) or above.
</Info>

For an outline of the differences between Instant Voice Clones and Professional Voice Clones, refer to the [Voices capability](/docs/overview/capabilities/voices) guide.

<Warning>
  If you are unsure about what is permissible from a legal standpoint, please consult the [Terms of
  Service](https://elevenlabs.io/terms-of-use) and our [AI Safety
  information](https://elevenlabs.io/safety) for more information.
</Warning>

In terms of creating a PVC via the API, it contains considerably more steps than creating an Instant Voice Clone. This is due to the fact that PVCs are more complex and require more data and fine-tuning to create a high quality clone.

## Using the Professional Voice Clone API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Create a PVC voice">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code to create a PVC voice:

    <CodeBlock>
      ```python maxLines=0
      # example.py
      import os
      import time
      import base64
      from contextlib import ExitStack
      from io import BytesIO
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      voice = elevenlabs.voices.pvc.create(
          name="My Professional Voice Clone",
          language="en",
          description="A professional voice clone of my voice"
      )

      print(voice)
      ```

      ```typescript maxLines=0
      // example.mts
      import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      import fs from "node:fs";

      const elevenlabs = new ElevenLabsClient();

      const voice = await elevenlabs.voices.pvc.create({
          name: "My Professional Voice Clone",
          language: "en",
          description: "A professional voice clone of my voice",
      });

      console.log(voice.voiceId);
      ```
    </CodeBlock>
  </Step>

  <Step title="Upload audio files">
    Next we'll upload the audio sample files that will be used to train the PVC. Review the [Tips and suggestions](/docs/creative-platform/voices/voice-cloning/professional-voice-cloning#tips-and-suggestions) section of the PVC product guide for more information on how to get best results from your audio files.

    <CodeBlock>
      ```python maxLines=0
      # Define the list of file paths explicitly
      # Replace with the paths to your audio and/or video files.
      # The more files you add, the better the clone will be.
      sample_file_paths = [
          "/path/to/your/first_sample.mp3",
          "/path/to/your/second_sample.wav",
          "relative/path/to/another_sample.mp4"
      ]

      samples = None

      files_to_upload = []
      # Use ExitStack to manage multiple open files
      with ExitStack() as stack:
          for filepath in sample_file_paths:
              # Open each file and add it to the stack
              audio_file = stack.enter_context(open(filepath, "rb"))
              filename = os.path.basename(filepath)

              # Create a File object for the SDK
              files_to_upload.append(
                  BytesIO(audio_file.read())
              )

          samples = elevenlabs.voices.pvc.samples.create(
              voice_id=voice.voice_id,
              files=files_to_upload # Pass the list of File objects
          )
      ```

      ```typescript
      const samples = await elevenlabs.voices.pvc.samples.create(voice.voiceId, {
          // Replace with the paths to your audio and/or video files.
          // The more files you add, the better the clone will be.
          files: [fs.createReadStream("/path/to/your/audio/file.mp3")],
      })
      ```
    </CodeBlock>
  </Step>

  <Step title="Begin speaker separation">
    This step will attempt to separate the audio files into individual speakers. This is required if you are uploading audio with multiple speakers.

    <CodeBlock>
      ```python maxLines=0
      sample_ids_to_check = []
      for sample in samples:
          if sample.sample_id:
              print(f"Starting separation for sample: {sample.sample_id}")
              elevenlabs.voices.pvc.samples.speakers.separate(
                  voice_id=voice.voice_id,
                  sample_id=sample.sample_id
              )
              sample_ids_to_check.append(sample.sample_id)

      while sample_ids_to_check:
          # Create a copy of the list to iterate over, so we can remove items from the original
          ids_in_batch = list(sample_ids_to_check)
          for sample_id in ids_in_batch:
              status_response = elevenlabs.voices.pvc.samples.speakers.get(
                  voice_id=voice.voice_id,
                  sample_id=sample_id
              )
              status = status_response.status
              print(f"Sample {sample_id} status: {status}")
              if status == "completed" or status == "failed":
                  sample_ids_to_check.remove(sample_id)

          if sample_ids_to_check:
              # Wait before the next poll cycle
              time.sleep(5) # Wait for 5 seconds

      print("All samples have been processed or removed from polling.")
      ```

      ```typescript maxLines=0
      // Trigger the speaker separation action, this will take some time to complete
      for (const sample of samples) {
          if (sample.sampleId) {
              await elevenlabs.voices.pvc.samples.speakers.separate(voiceId, sample.sampleId);
          }
      }

      // Check the status of the speaker separation action
      const ids = samples.map((sample) => sample.sampleId);
      const interval = setInterval(async () => {
          // Poll the status of the speaker separation action
          for (const id of ids) {
              if (!id) continue;

              const { status } = await elevenlabs.voices.pvc.samples.speakers.get(voice.voiceId, id);
              console.log(`Sample ${id} status: ${status}`);
              if (status === "completed" || status === "failed") {
                  ids.splice(ids.indexOf(id), 1);
              }

              if (ids.length === 0) {
                  clearInterval(interval);
                  console.log("All samples have been processed or removed from polling");
              }
          }
      }, 5000);
      ```
    </CodeBlock>
  </Step>

  <Step title="Retrieve speaker audio">
    <Warning>
      Since the previous step will take some time to complete, the following step should be run in a separate process after the previous step has completed.
    </Warning>

    Once speaker separation is complete, you will have a list of speakers for each sample. In the case of samples with multiple speakers, you will have to pick the speaker you want to use for the PVC. To identify the speaker, you can retrieve the audio for each speaker and listen to them.

    <CodeBlock>
      ```python maxLines=0
      # Get the list of samples from the voice created in Step 3
      voice = elevenlabs.voices.get(voice_id=voice_id)

      samples = voice.samples

      # Loop over each sample and save the audio for each speaker to a file
      speaker_audio_output_dir = "path/to/speakers/"
      if not os.path.exists(speaker_audio_output_dir):
          os.makedirs(speaker_audio_output_dir)

      for sample in samples:
          speaker_info = elevenlabs.voices.pvc.samples.speakers.get(
              voice_id=voice.voice_id,
              sample_id=sample.sample_id
          )

          # Proceed only if separation is actually complete
          if getattr(speaker_info, 'status', 'unknown') != "completed":
              continue

          if hasattr(speaker_info, 'speakers') and speaker_info.speakers:
              speaker_list = speaker_info.speakers
              if isinstance(speaker_info.speakers, dict):
                  speaker_list = speaker_info.speakers.values()

              for speaker in speaker_list:
                  audio_response = elevenlabs.voices.pvc.samples.speakers.audio.get(
                      voice_id=voice.voice_id,
                      sample_id=sample.sample_id,
                      speaker_id=speaker.speaker_id
                  )

                  audio_base64 = audio_response.audio_base_64
                  audio_data = base64.b64decode(audio_base64)
                  output_filename = os.path.join(speaker_audio_output_dir, f"sample_{sample.sample_id}_speaker_{speaker.speaker_id}.mp3")

                  with open(output_filename, "wb") as f:
                      f.write(audio_data)
      ```

      ```typescript maxLines=0
      // Get the list of samples from the voice created in Step 3
      const { samples } = await elevenlabs.voices.get(voiceId);

      // After separation is completed, get the list of speakers and their audio
      if (samples) {
          for (const sample of samples) {
              if (!sample.sampleId) continue;

              const { speakers } = await elevenlabs.voices.pvc.samples.speakers.get(voiceId, sample.sampleId)

              if (speakers) {
                  for (const speaker of Object.values(speakers)) {
                      if (!speaker || !speaker.speakerId) continue;
                      const { audioBase64 } = await elevenlabs.voices.pvc.samples.speakers.audio.get(voiceId, sample.sampleId, speaker.speakerId);
                      const audioBuffer = Buffer.from(audioBase64, 'base64');

                      // Write the audio to a file
                      // Note which speaker ID you wish to use for the PVC
                      fs.writeFileSync(`path/to/speakers/sample_${sample.sampleId}_speaker_${speaker.speakerId}.mp3`, audioBuffer);
                  }
              }
          }
      }
      ```
    </CodeBlock>
  </Step>

  <Step title="Update samples with speaker IDs">
    Once speaker separation is complete, you can update the samples to select which speaker you want to use for the PVC.

    <CodeBlock>
      ```python
      elevenlabs.voices.pvc.samples.update(
          voice_id=voice.voice_id,
          sample_id=sample.sample_id,
          selected_speaker_ids=[speaker.speaker_id]
      )
      ```

      ```typescript
      await elevenlabs.voices.pvc.samples.update(voice.voiceId, sample.sampleId, {
          selectedSpeakerIds: [speaker.speakerId],
      })
      ```

      Repeat this process for each sample for with multiple speakers.
    </CodeBlock>
  </Step>

  <Step title="Verify the PVC">
    Before training can begin, a verification step is required to ensure you have permission to use the voice. First request the verification CAPTCHA.

    <CodeBlock>
      ```python
      captcha_response = elevenlabs.voices.pvc.verification.captcha.get(voice.voice_id)

      # Save captcha image to file
      captcha_buffer = base64.b64decode(captcha_response)
      with open('captcha.png', 'wb') as f:
          f.write(captcha_buffer)
      ```

      ```typescript
      const captchaResponse = await elevenlabs.voices.pvc.verification.captcha.get(voice.voiceId);

      // Save captcha image to file
      const captchaBuffer = Buffer.from(captchaResponse, 'base64');
      fs.writeFileSync('path/to/captcha.png', captchaBuffer);
      ```
    </CodeBlock>

    The image contains several lines of text that the voice owner will need to read out loud and record. Once done, submit the recording to verify the identity of the voice's owner.

    <CodeBlock>
      ```python
      elevenlabs.voices.pvc.verification.captcha.verify(
          voice_id=voice.voice_id,
          recording=open('path/to/recording.mp3', 'rb')
      )
      ```

      ```typescript
      await elevenlabs.voices.pvc.verification.captcha.verify(voice.voiceId, {
      	recording: fs.createReadStream("/path/to/recording.mp3"),
      })
      ```
    </CodeBlock>
  </Step>

  <Step title="(Optional) Request manual verification">
    If you are unable to verify the CAPTCHA, you can request manual verification. Note that this will take longer to process.

    This should only be used if the previous verification steps have failed or are not possible, for instance if the voice owner is visually impaired.

    For a list of the files that are required for manual verification, please contact support as each case may be unique.

    <CodeBlock>
      ```python
      elevenlabs.voices.pvc.verification.request(
          voice_id=voice.voice_id,
          files=[open('path/to/verification/files.txt', 'rb')],
      )
      ```

      ```typescript
      await elevenlabs.voices.pvc.verification.request(voice.voiceId, {
          files: [fs.createReadStream("/path/to/verification/files.txt")],
      });
      ```
    </CodeBlock>
  </Step>

  <Step title="Train the PVC">
    Next, begin the training process. This will take some time to complete based on the length and number of samples provided.

    <CodeBlock>
      ```python maxLines=0
      elevenlabs.voices.pvc.train(
          voice_id=voice.voice_id,
          # Specify the model the PVC should be trained on
          model_id="eleven_multilingual_v2"
      )

      # Poll the fine tuning status until it is complete or fails
      # This example specifically checks for the eleven_multilingual_v2 model
      while True:
          voice_details = elevenlabs.voices.get(voice_id=voice.voice_id)
          fine_tuning_state = None
          if voice_details.fine_tuning and voice_details.fine_tuning.state:
              fine_tuning_state = voice_details.fine_tuning.state.get("eleven_multilingual_v2")

          if fine_tuning_state:
              progress = None
              if voice_details.fine_tuning.progress and voice_details.fine_tuning.progress.get("eleven_multilingual_v2"):
                  progress = voice_details.fine_tuning.progress.get("eleven_multilingual_v2")
              print(f"Fine tuning progress: {progress}")

              if fine_tuning_state == "fine_tuned" or fine_tuning_state == "failed":
                  print("Fine tuning completed or failed")
                  break
          # Wait for 5 seconds before polling again
          time.sleep(5)
      ```

      ```typescript maxLines=0
      await elevenlabs.voices.pvc.train(voiceId, {
          // Specify the model the PVC should be trained on
          modelId: "eleven_multilingual_v2",
      });

      // Poll the fine tuning status until it is complete or fails
      // This example specifically checks for the eleven_multilingual_v2 model
      const interval = setInterval(async () => {
          const { fineTuning } = await elevenlabs.voices.get(voiceId);
          if (!fineTuning) return;

          console.log(`Fine tuning progress: ${fineTuning?.progress?.eleven_multilingual_v2}`);

          if (fineTuning?.state?.eleven_multilingual_v2 === "fine_tuned" || fineTuning?.state?.eleven_multilingual_v2 === "failed") {
              clearInterval(interval);
              console.log("Fine tuning completed or failed");
          }
      }, 5000);
      ```
    </CodeBlock>
  </Step>

  <Step title="Use the newly created voice">
    Once the PVC is verified, you can use it in the same way as any other voice. See the [Text to Speech quickstart](/docs/developers/quickstart) for more information on how to use a voice.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/voices/pvc/create) for more information on creating a Professional Voice Clone.


# Voice Design quickstart

> Learn how to design a voice via a prompt using the Voice Design API.

This guide will show you how to design a voice via a prompt using the Voice Design API.

## Using the Voice Design API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Designing a voice via a prompt has two steps:

    1. Generate previews based on a prompt.
    2. Select the best preview and use it to create a new voice.

    We'll start by generating previews based on a prompt.

    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import base64

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      voices = elevenlabs.text_to_voice.design(
          model_id="eleven_multilingual_ttv_v2",
          voice_description="A massive evil ogre speaking at a quick pace. He has a silly and resonant tone.",
          text="Your weapons are but toothpicks to me. Surrender now and I may grant you a swift end. I've toppled kingdoms and devoured armies. What hope do you have against me?",
      )

      for preview in voices.previews:
          # Convert base64 to audio buffer
          audio_buffer = base64.b64decode(preview.audio_base_64)

          print(f"Playing preview: {preview.generated_voice_id}")

          play(audio_buffer)
      ```

      ```typescript maxLines=0
      // example.ts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      import { Readable } from 'node:stream';
      import { Buffer } from 'node:buffer';

      const elevenlabs = new ElevenLabsClient();

      const { previews } = await elevenlabs.textToVoice.design({
          modelId: "eleven_multilingual_ttv_v2",
          voiceDescription: "A massive evil ogre speaking at a quick pace. He has a silly and resonant tone.",
          text: "Your weapons are but toothpicks to me. Surrender now and I may grant you a swift end. I've toppled kingdoms and devoured armies. What hope do you have against me?",
      });

      for (const preview of previews) {
          // Convert base64 to buffer and create a Readable stream
          const audioStream = Readable.from(Buffer.from(preview.audioBase64, 'base64'));

          console.log(`Playing preview: ${preview.generatedVoiceId}`);

          // Play the audio using the stream
          await play(audioStream);
      }
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the generated voice previews playing through your speakers, one at a time.
  </Step>

  <Step title="Add generated voice to your library">
    Once you've generated the previews and picked your favorite, you can add it to your voice library via the generated voice ID so it can be used with other APIs.

    <CodeBlocks>
      ```python
      voice = elevenlabs.text_to_voice.create(
          voice_name="Jolly giant",
          voice_description="A huge giant, at least as tall as a building. A deep booming voice, loud and jolly.",
          # The generated voice ID of the preview you want to use,
          # using the first in the list for this example
          generated_voice_id=voices.previews[0].generated_voice_id
      )

      print(voice.voice_id)
      ```

      ```typescript
      const voice = await elevenlabs.textToVoice.create({
          voiceName: "Jolly giant",
          voiceDescription: "A huge giant, at least as tall as a building. A deep booming voice, loud and jolly.",
          // The generated voice ID of the preview you want to use,
          // using the first in the list for this example
          generatedVoiceId: previews[0].generatedVoiceId
      });

      // The ID of the newly created voice, use this to reference the voice in other APIs
      console.log(voice.voiceId);
      ```
    </CodeBlocks>
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/text-to-voice/design) for more information on the Voice Design API and its options.


# Voice Remixing quickstart

> Learn how to remix an existing voice to create a new one.

This guide will show you how to create an entirely new voice by remixing an existing one.

## Using the Voice Design API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make the API request">
    Remixing a voice is a two step process:

    1. Generate a preview of the new voice by providing a voice ID and a prompt.
    2. Create the new voice from the preview.

    We'll start by generating a preview of the new voice.

    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <Warning>
      You can only remix voices that were created by you. For example previously designed voices, IVC or PVC voices. You cannot remix voices from the voice library.
    </Warning>

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import base64

      load_dotenv()

      elevenlabs = ElevenLabs(
          api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      voices = elevenlabs.text_to_voice.remix(
          voice_id="JBFqnCBsd6RMkjVDRZzb"
          voice_description="Use a higher pitch and change to a Boston accent.",
          text="Of course I'm a Bostonian, I've lived here all my life!",
      )

      for preview in voices.previews:
          # Convert base64 to audio buffer
          audio_buffer = base64.b64decode(preview.audio_base_64)

          print(f"Playing preview: {preview.generated_voice_id}")

          play(audio_buffer)
      ```

      ```typescript maxLines=0
      // example.ts
      import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      import { Readable } from 'node:stream';
      import { Buffer } from 'node:buffer';

      const elevenlabs = new ElevenLabsClient();

      const { previews } = await elevenlabs.textToVoice.remix("JBFqnCBsd6RMkjVDRZzb", {
          voiceDescription: "Use a higher pitch and change to a Boston accent.",
          text: "Of course I'm a Bostonian, I've lived here all my life!",
      });

      for (const preview of previews) {
          // Convert base64 to buffer and create a Readable stream
          const audioStream = Readable.from(Buffer.from(preview.audioBase64, 'base64'));

          console.log(`Playing preview: ${preview.generatedVoiceId}`);

          // Play the audio using the stream
          await play(audioStream);
      }
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the generated voice previews playing through your speakers, one at a time.
  </Step>

  <Step title="Add generated voice to your library">
    Once you've generated the previews and picked your favorite, you can add it to your voice library via the generated voice ID so it can be used with other APIs.

    <CodeBlocks>
      ```python
      voice = elevenlabs.text_to_voice.create(
          voice_name="Bostonian",
          voice_description="A high pitched Bostonian accent.",
          # The generated voice ID of the preview you want to use,
          # using the first in the list for this example
          generated_voice_id=voices.previews[0].generated_voice_id
      )

      print(voice.voice_id)
      ```

      ```typescript
      const voice = await elevenlabs.textToVoice.create({
          voiceName: "Bostonian",
          voiceDescription: "A high pitched Bostonian accent.",
          // The generated voice ID of the preview you want to use,
          // using the first in the list for this example
          generatedVoiceId: previews[0].generatedVoiceId
      });

      // The ID of the newly created voice, use this to reference the voice in other APIs
      console.log(voice.voiceId);
      ```
    </CodeBlocks>
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/text-to-voice/remix) for more information on the Voice Design API and its options.


# Forced Alignment quickstart

> Learn how to use the Forced Alignment API to align text to audio.

This guide will show you how to use the Forced Alignment API to align text to audio.

## Using the Forced Alignment API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>
  </Step>

  <Step title="Make the API request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    <CodeBlocks>
      ```python maxLines=0
      # example.py
      import os
      from io import BytesIO
      from elevenlabs.client import ElevenLabs
      import requests
      from dotenv import load_dotenv

      load_dotenv()

      elevenlabs = ElevenLabs(
          api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio_url = (
          "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      )
      response = requests.get(audio_url)
      audio_data = BytesIO(response.content)

      # Perform the text-to-speech conversion
      transcription = elevenlabs.forced_alignment.create(
          file=audio_data,
          text="With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects."
      )

      print(transcription)
      ```

      ```typescript maxLines=0
      // example.ts
      import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
      import "dotenv/config";
      const elevenlabs = new ElevenLabsClient();

      const response = await fetch(
          "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
      );
      const audioBlob = new Blob([await response.arrayBuffer()], { type: "audio/mp3" });

      const transcript = await elevenlabs.forcedAlignment.create({
          file: audioBlob,
          text: "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects."
      })

      console.log(transcript);
      ```
    </CodeBlocks>
  </Step>

  <Step title="Execute the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should see the transcript of the audio file with exact timestamps printed to the console.
  </Step>
</Steps>

## Next steps

Explore the [API reference](/docs/api-reference/forced-alignment/create) for more information on the Forced Alignment API and its options.


# Multi-Context Websocket

> Learn how to build real time voice agents using our multi-context WebSocket API for dynamic and responsive interactions.

<Warning title="Advanced">
  Orchestrating voice agents using this multi-context WebSocket API is a complex task recommended
  for advanced developers. For a more managed solution, consider exploring our [Agents Platform
  product](/docs/agents-platform/overview), which simplifies many of these challenges.
</Warning>

<Info>
  Multi-context WebSockets are not available for the 

  `eleven_v3`

   model.
</Info>

## Overview

Building responsive voice agents requires the ability to manage audio streams dynamically, handle interruptions gracefully, and maintain natural-sounding speech across conversational turns. Our multi-context WebSocket API for Text to Speech (TTS) is specifically designed for these scenarios.

This API extends our [standard TTS WebSocket functionality](/docs/developers/websockets) by introducing the concept of "contexts." Each context operates as an independent audio generation stream within a single WebSocket connection. This allows you to:

* Manage multiple lines of speech concurrently (e.g., agent speaking while preparing a response to a user interruption).
* Seamlessly handle user barge-ins by closing an existing speech context and initiating a new one.
* Maintain prosodic consistency for utterances within the same logical context.
* Optimize resource usage by selectively closing contexts that are no longer needed.

<Warning>
  The multi-context WebSocket API is optimized for voice applications and is not intended for
  generating multiple unrelated audio streams simultaneously. Each connection is limited to 5
  concurrent contexts to reflect this.
</Warning>

This guide will walk you through connecting to the multi-context WebSocket, managing contexts, and applying best practices for building engaging voice agents.

### Best practices

<Note>
  These best practices are essential for building responsive, efficient voice agents with our
  multi-context WebSocket API.
</Note>

<Steps>
  <Step title="Use a single WebSocket connection">
    Establish one WebSocket connection for each end-user session. This reduces overhead and latency
    compared to creating multiple connections. Within this single connection, you can manage
    multiple contexts for different parts of the conversation.
  </Step>

  <Step title="Stream responses in chunks, generate sentences">
    When generating long responses, stream the text in smaller chunks and use the `flush: true` flag
    at the end of complete sentences. This improves the quality of the generated audio and improves
    responsiveness.
  </Step>

  <Step title="Handle interruptions gracefully">
    Stream text into one context until an interruption occurs, then create a new context and close
    the existing one. This approach ensures smooth transitions when the conversation flow changes.
  </Step>

  <Step title="Manage context lifecycle">
    Close unused contexts promptly. The server can maintain up to 5 concurrent contexts per
    connection, but you should close contexts when they are no longer needed.
  </Step>

  <Step title="Prevent context timeouts">
    Contexts by default timeout after 20 seconds and are closed automatically. The inactivity
    timeout is a websocket level parameter that applies to all contexts and can be up to 180 seconds
    if needed. Send an empty text message on a context to reset the timeout clock.
  </Step>
</Steps>

### Handling interuptions

When a user interrupts your agent, you should [close the current context](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-multi-stream-input#send.Close-Context) and [create a new one](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-multi-stream-input#send.Initialise-Context):

<CodeBlocks>
  ```python
  async def handle_interruption(websocket, old_context_id, new_context_id, new_response):
      # Close the existing context that was interrupted
      await websocket.send(json.dumps({
          "context_id": old_context_id,
          "close_context": True
      }))
      print(f"Closed interrupted context '{old_context_id}'")

      # Create a new context for the new response
      await send_text_in_context(websocket, new_response, new_context_id)
  ```

  ```javascript
  function handleInterruption(websocket: WebSocket, oldContextId: string, newContextId: string, newResponse: string) {
    // Close the existing context that was interrupted
    websocket.send(JSON.stringify({
      context_id: oldContextId,
      close_context: true
    }));
    console.log(`Closed interrupted context '${oldContextId}'`);

    // Create a new context for the new response
    sendTextInContext(websocket, newResponse, newContextId);
  }
  ```
</CodeBlocks>

### Keeping a context alive

Contexts automatically timeout after [a default of 20 seconds of inactivity](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-multi-stream-input#request.query.inactivity_timeout). If you need to keep a context alive without generating text (for example, during a processing delay), you can send an empty text message to reset the timeout clock.

<CodeBlocks>
  ```python
  async def keep_context_alive(websocket, context_id):
      await websocket.send(json.dumps({
          "context_id": context_id,
          "text": ""
      }))
  ```

  ```javascript
  function handleInterruption(websocket: WebSocket, contextId: string) {
    // Close the existing context that was interrupted
    websocket.send(JSON.stringify({
      context_id: oldContextId,
      text: ""
    }));
  }
  ```
</CodeBlocks>

### Closing the WebSocket connection

When your conversation ends, you can clean up all contexts by [closing the socket](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-multi-stream-input#send.Close-Socket):

<CodeBlocks>
  ```python
  async def end_conversation(websocket):
      # This will close all contexts and close the connection
      await websocket.send(json.dumps({
          "close_socket": True
      }))
      print("Ending conversation and closing WebSocket")`
  ```

  ```javascript
  function endConversation(websocket: WebSocket) {
    // This will close all contexts and close the connection
    websocket.send(JSON.stringify({
      close_socket: true
    }));
    console.log("Ending conversation and closing WebSocket");
  }
  ```
</CodeBlocks>

## Complete conversational agent example

### Requirements

* An ElevenLabs account with an API key (learn how to [find your API key](/docs/api-reference/authentication)).
* Python or Node.js (or another JavaScript runtime) installed on your machine.
* Familiarity with WebSocket communication. We recommend reading our [guide on standard WebSocket streaming](/docs/developers/websockets) for foundational concepts.

### Setup

Install the necessary dependencies for your chosen language:

<CodeBlocks>
  ```python
  pip install python-dotenv websockets
  ```

  ```javascript
  npm install dotenv ws
  for TypeScript, you might also want types:
  npm install @types/dotenv @types/ws --save-dev
  ```
</CodeBlocks>

Create a .env file in your project directory to store your API key:

<CodeBlocks>
  ```python .env
  ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
  ```
</CodeBlocks>

### Example voice agent

<Note>
  This code is provided as an example and is not intended for production usage
</Note>

<CodeBlocks>
  ```python maxLines=100
  import os
  import json
  import asyncio
  import websockets
  from dotenv import load_dotenv

  load_dotenv()
  ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
  VOICE_ID = "your_voice_id"
  MODEL_ID = "eleven_flash_v2_5"

  WEBSOCKET_URI = f"wss://api.elevenlabs.io/v1/text-to-speech/{VOICE_ID}/multi-stream-input?model_id={MODEL_ID}"

  async def send_text_in_context(websocket, text, context_id, voice_settings=None):
      """Send text to be synthesized in the specified context."""
      message = {
          "text": text,
          "context_id": context_id,
      }

      # Only include voice_settings for the first message in a context
      if voice_settings:
          message["voice_settings"] = voice_settings

      await websocket.send(json.dumps(message))

  async def continue_context(websocket, text, context_id):
      """Add more text to an existing context."""
      await websocket.send(json.dumps({
          "text": text,
          "context_id": context_id
      }))

  async def flush_context(websocket, context_id):
      """Force generation of any buffered audio in the context."""
      await websocket.send(json.dumps({
          "context_id": context_id,
          "flush": True
      }))

  async def handle_interruption(websocket, old_context_id, new_context_id, new_response):
      """Handle user interruption by closing current context and starting a new one."""
      # Close the existing context that was interrupted
      await websocket.send(json.dumps({
          "context_id": old_context_id,
          "close_context": True
      }))

      # Create a new context for the new response
      await send_text_in_context(websocket, new_response, new_context_id)

  async def end_conversation(websocket):
      """End the conversation and close the WebSocket connection."""
      await websocket.send(json.dumps({
          "close_socket": True
      }))

  async def receive_messages(websocket):
      """Process incoming WebSocket messages."""
      context_audio = {}
      try:
          async for message in websocket:
              data = json.loads(message)
              context_id = data.get("contextId", "default")

              if data.get("audio"):
                  print(f"Received audio for context '{context_id}'")

              if data.get("is_final"):
                  print(f"Context '{context_id}' completed")
      except (websockets.exceptions.ConnectionClosed, asyncio.CancelledError):
          print("Message receiving stopped")

  async def conversation_agent_demo():
      """Run a complete conversational agent demo."""
      # Connect with API key in headers
      async with websockets.connect(
          WEBSOCKET_URI,
          max_size=16 * 1024 * 1024,
          additional_headers={"xi-api-key": ELEVENLABS_API_KEY}
      ) as websocket:
          # Start receiving messages in background
          receive_task = asyncio.create_task(receive_messages(websocket))

          # Initial agent response
          await send_text_in_context(
              websocket,
              "Hello! I'm your virtual assistant. I can help you with a wide range of topics. What would you like to know about today?",
              "greeting"
          )

          # Wait a bit (simulating user listening)
          await asyncio.sleep(2)

          # Simulate user interruption
          print("USER INTERRUPTS: 'Can you tell me about the weather?'")

          # Handle the interruption by closing current context and starting new one
          await handle_interruption(
              websocket,
              "greeting",
              "weather_response",
              "I'd be happy to tell you about the weather. Currently in your area, it's 72 degrees and sunny with a slight chance of rain later this afternoon."
          )

          # Add more to the weather context
          await continue_context(
              websocket,
              " If you're planning to go outside, you might want to bring a light jacket just in case.",
              "weather_response"
          )

          # Flush at the end of this turn to ensure all audio is generated
          await flush_context(websocket, "weather_response")

          # Wait a bit (simulating user listening)
          await asyncio.sleep(3)

          # Simulate user asking another question
          print("USER: 'What about tomorrow?'")

          # Create a new context for this response
          await send_text_in_context(
              websocket,
              "Tomorrow's forecast shows temperatures around 75 degrees with partly cloudy skies. It should be a beautiful day overall!",
              "tomorrow_weather"
          )

          # Flush and close this context
          await flush_context(websocket, "tomorrow_weather")
          await websocket.send(json.dumps({
              "context_id": "tomorrow_weather",
              "close_context": True
          }))

          # End the conversation
          await asyncio.sleep(2)
          await end_conversation(websocket)

          # Cancel the receive task
          receive_task.cancel()
          try:
              await receive_task
          except asyncio.CancelledError:
              pass

  if __name__ == "__main__":
      asyncio.run(conversation_agent_demo())

  ```

  ```javascript maxLines=100
  // Import required modules
  import dotenv from 'dotenv';
  import fs from 'fs';
  import WebSocket from 'ws';

  // Load environment variables
  dotenv.config();
  const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;
  const VOICE_ID = 'your_voice_id';
  const MODEL_ID = 'eleven_flash_v2_5';

  const WEBSOCKET_URI = `wss://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}/multi-stream-input?model_id=${MODEL_ID}`;

  // Function to send text in a specific context
  function sendTextInContext(websocket, text, contextId, voiceSettings = null) {
    const message = {
      text: text,
      context_id: contextId,
    };

    // Only include voice_settings for the first message in a context
    if (voiceSettings) {
      message.voice_settings = voiceSettings;
    }

    websocket.send(JSON.stringify(message));
  }

  // Function to continue an existing context with more text
  function continueContext(websocket, text, contextId) {
    websocket.send(
      JSON.stringify({
        text: text,
        context_id: contextId,
      })
    );
  }

  // Function to flush a context, forcing generation of buffered audio
  function flushContext(websocket, contextId) {
    websocket.send(
      JSON.stringify({
        context_id: contextId,
        flush: true,
      })
    );
  }

  // Function to handle user interruption
  function handleInterruption(websocket, oldContextId, newContextId, newResponse) {
    // Close the existing context that was interrupted
    websocket.send(
      JSON.stringify({
        context_id: oldContextId,
        close_context: true,
      })
    );

    // Create a new context for the new response
    sendTextInContext(websocket, newResponse, newContextId);
  }

  // Function to end the conversation and close the connection
  function endConversation(websocket) {
    websocket.send(
      JSON.stringify({
        close_socket: true,
      })
    );
  }

  // Function to run the conversation agent demo
  async function conversationAgentDemo() {
    // Connect to WebSocket with API key in headers
    const websocket = new WebSocket(WEBSOCKET_URI, {
      headers: {
        'xi-api-key': ELEVENLABS_API_KEY,
      },
      maxPayload: 16 * 1024 * 1024,
    });

    // Set up event handlers
    websocket.on('open', () => {
      // Initial agent response
      sendTextInContext(
        websocket,
        "Hello! I'm your virtual assistant. I can help you with a wide range of topics. What would you like to know about today?",
        'greeting'
      );

      // Simulate wait time (user listening)
      setTimeout(() => {
        // Simulate user interruption
        console.log("USER INTERRUPTS: 'Can you tell me about the weather?'");

        // Handle the interruption
        handleInterruption(
          websocket,
          'greeting',
          'weather_response',
          "I'd be happy to tell you about the weather. Currently in your area, it's 72 degrees and sunny with a slight chance of rain later this afternoon."
        );

        // Add more to the weather context
        setTimeout(() => {
          continueContext(
            websocket,
            " If you're planning to go outside, you might want to bring a light jacket just in case.",
            'weather_response'
          );

          // Flush at the end of this turn
          flushContext(websocket, 'weather_response');

          // Simulate wait time (user listening)
          setTimeout(() => {
            // Simulate user asking another question
            console.log("USER: 'What about tomorrow?'");

            // Create a new context for this response
            sendTextInContext(
              websocket,
              "Tomorrow's forecast shows temperatures around 75 degrees with partly cloudy skies. It should be a beautiful day overall!",
              'tomorrow_weather'
            );

            // Flush and close this context
            flushContext(websocket, 'tomorrow_weather');
            websocket.send(
              JSON.stringify({
                context_id: 'tomorrow_weather',
                close_context: true,
              })
            );

            // End the conversation
            setTimeout(() => {
              endConversation(websocket);
            }, 2000);
          }, 3000);
        }, 500);
      }, 2000);
    });

    // Handle incoming messages
    websocket.on('message', (message) => {
      try {
        const data = JSON.parse(message);
        const contextId = data.contextId || 'default';

        if (data.audio) {
          //do stuff
        }

        if (data.is_final) {
          console.log(`Context '${contextId}' completed`);
        }
      } catch (error) {
        console.error('Error parsing message:', error);
      }
    });

    // Handle WebSocket closure
    websocket.on('close', () => {
      console.log('WebSocket connection closed');
    });

    // Handle WebSocket errors
    websocket.on('error', (error) => {
      console.error('WebSocket error:', error);
    });
  }

  // Run the demo
  conversationAgentDemo();
  ```
</CodeBlocks>


# Libraries & SDKs

> Explore language-specific libraries for using the ElevenLabs API.

## Official REST API libraries

ElevenLabs provides officially supported libraries that are updated with the latest features available in the [REST API](/docs/api-reference/introduction).

| Language          | GitHub                                                           | Package Manager                                                |
| ----------------- | ---------------------------------------------------------------- | -------------------------------------------------------------- |
| Python            | [GitHub README](https://github.com/elevenlabs/elevenlabs-python) | [PyPI](https://pypi.org/project/elevenlabs/)                   |
| Javascript (Node) | [GitHub README](https://github.com/elevenlabs/elevenlabs-js)     | [npm](https://www.npmjs.com/package/@elevenlabs/elevenlabs-js) |

## Official Agents Platform libraries

These libraries are designed for use with ElevenLabs [Agents Platform](/docs/agents-platform/overview).

| Language     | Documentation                                            | Package Manager                                                                 |
| ------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Javascript   | [Docs](/docs/agents-platform/libraries/java-script)      | [npm](https://www.npmjs.com/package/@elevenlabs/client)                         |
| React        | [Docs](/docs/agents-platform/libraries/react)            | [npm](https://www.npmjs.com/package/@elevenlabs/react)                          |
| React Native | [Docs](/docs/agents-platform/libraries/react-native)     | [npm](https://www.npmjs.com/package/@elevenlabs/react-native)                   |
| Python       | [Docs](/docs/agents-platform/libraries/python)           | [PyPI](https://pypi.org/project/elevenlabs/)                                    |
| Swift        | [Docs](/docs/agents-platform/libraries/swift)            | [Github](https://github.com/elevenlabs/ElevenLabsSwift)                         |
| Kotlin       | [Docs](/docs/agents-platform/libraries/kotlin)           | [Maven](https://central.sonatype.com/artifact/io.elevenlabs/elevenlabs-android) |
| Flutter      | [Docs](https://github.com/elevenlabs/elevenlabs-flutter) | [Pub](https://pub.dev/packages/elevenlabs_agents)                               |

## Third-party libraries

These libraries are not officially supported by ElevenLabs, but are community-maintained.

| Library       | Documentation                                                                | Package Manager                                              |
| ------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Vercel AI SDK | [Docs](/docs/developers/guides/cookbooks/speech-to-text/batch/vercel-ai-sdk) | [npm](https://www.npmjs.com/package/ai)                      |
| .NET          | [Docs](https://github.com/RageAgainstThePixel/ElevenLabs-DotNet)             | [NuGet](https://www.nuget.org/packages/ElevenLabs-DotNet)    |
| Unity         | [Docs](https://github.com/RageAgainstThePixel/com.rest.elevenlabs)           | [OpenUPM](https://openupm.com/packages/com.rest.elevenlabs/) |


# Errors

> Explore error messages and solutions.

## API errors

ElevenLabs uses standard HTTP status codes to indicate the success or failure of a request. Additionally, all API requests return a JSON object with a `detail` property that contains information about the error.

In general, a `200` HTTP status code indicates a successful request. A `4xx` code indicates a problem with the request, like an invalid parameter or missing required field. A `500` HTTP status code indicates a problem with ElevenLabs' servers, which should be rare.

### Error properties

| Property     | Description                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `type`       | The type of error that occurred. See the table below for possible values.                                                 |
| `code`       | The code of the error. These are more specific than the type, and can be used to determine the cause of the error.        |
| `message`    | The message of the error. This provides more details about the error.                                                     |
| `status`     | The status of the error. This is a legacy field that is no longer used, instead use the `code` property.                  |
| `request_id` | The request ID of the error. This is a unique identifier for the request that can be used to troubleshoot the error.      |
| `param`      | The parameter that caused the error. In the case of a validation error, this will indicate the parameter that is invalid. |

### Example error response

Here's the response for an API request that used an incorrect model ID:

```json
{
  "detail": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.",
    "status": "invalid_parameters",
    "request_id": "3c807fc4c3a1705f9638ecc764a91c01",
    "param": "keyterms"
  }
}
```

Using the error properties, we can see that the error is a validation error, and the code is `invalid_parameters`. The message provides more details about the error, and the `request_id` is a unique identifier for the request that can be used to troubleshoot the error. The `param` property indicates the parameter that caused the error.

### SDK error handling

The ElevenLabs SDKs provide typed error classes that give you access to the error details.

<CodeBlock>
  ```python
  from elevenlabs import ElevenLabs, ApiError

  elevenlabs = ElevenLabs()

  try:
      audio = elevenlabs.text_to_speech.convert(
          voice_id="invalid-voice-id",
          model_id="eleven_v3",
          text="Hello, world!",
      )
  except ApiError as e:
      print(f"Status code: {e.status_code}")

      # Access the error body
      if e.body and "detail" in e.body:
          detail = e.body["detail"]
          print(f"Error type: {detail.get('type')}")
          print(f"Error code: {detail.get('code')}")
          print(f"Message: {detail.get('message')}")
          print(f"Request ID: {detail.get('request_id')}")

          # Handle specific error types
          if detail.get("type") == "rate_limit_error":
              print("Rate limited - implement exponential backoff")
          elif detail.get("type") == "authentication_error":
              print("Check your API key")
  ```

  ```typescript
  import { ElevenLabs, ElevenLabsError } from 'elevenlabs';

  const elevenlabs = new ElevenLabs();

  try {
    const audio = await elevenlabs.textToSpeech.convert('invalid-voice-id', {
      text: 'Hello, world!',
      modelId: 'eleven_v3',
    });
  } catch (error) {
    if (error instanceof ElevenLabsError) {
      console.log(`Status code: ${error.statusCode}`);

      // Access the error body
      const detail = (error.body as any)?.detail;
      if (detail) {
        console.log(`Error type: ${detail.type}`);
        console.log(`Error code: ${detail.code}`);
        console.log(`Message: ${detail.message}`);
        console.log(`Request ID: ${detail.request_id}`);

        // Handle specific error types
        if (detail.type === 'rate_limit_error') {
          console.log('Rate limited - implement exponential backoff');
        } else if (detail.type === 'authentication_error') {
          console.log('Check your API key');
        }
      }
    }
  }
  ```

  If you're unable to resolve the error, [contact our support team](https://help.elevenlabs.io/hc/en-us/requests/new) with the `request_id` from the error response, the full error message, and steps to reproduce the issue.
</CodeBlock>

#### Rate limiting and concurrency

If you receive a 429 HTTP status code, it means you have either made too many requests in a short period of time and exceeded the rate limit for the API endpoint, or you have exceeded the concurrency limit for the API endpoint. The error `code` will be `rate_limit_exceeded` or `concurrent_limit_exceeded` respectively.

In the case of rate limiting, you should implement exponential backoff in your code when a 429 error is received. This means adding a delay before retrying the request.

In the case of concurrency, you should wait for the current requests to complete before making new ones. See the [Concurrency and priority](/docs/overview/models#concurrency-and-priority) section for more information.

### Error types

An error comes with a `type` property that indicates the type of error that occurred. See the table below for possible values.

| Type                   | Description                                                                   | HTTP Status Code |
| ---------------------- | ----------------------------------------------------------------------------- | ---------------- |
| `validation_error`     | The request contains invalid parameter values.                                | 400              |
| `invalid_request`      | The request structure is malformed or missing required fields.                | 400              |
| `authentication_error` | Authentication failed - invalid or missing API key/token.                     | 401              |
| `payment_required`     | User has insufficient credits or payment is required.                         | 402              |
| `authorization_error`  | The authenticated user doesn't have the required permissions for this action. | 403              |
| `not_found`            | The requested resource was not found.                                         | 404              |
| `conflict`             | The request conflicts with the current state of the resource.                 | 409              |
| `rate_limit_error`     | Too many requests - try again later.                                          | 429              |
| `internal_error`       | An unexpected server error occurred.                                          | 500              |
| `service_unavailable`  | The service is temporarily unavailable, this should be a rare occurrence.     | 503              |

### Error codes

<table searchable>
  <thead>
    <tr>
      <th>
        Code
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    {/* NOT_FOUND (404) - Voice-related */}

    <tr>
      <td>
        `voice_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified voice ID does not exist. Verify the voice ID and try again.
      </td>
    </tr>

    <tr>
      <td>
        `sample_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified voice sample was not found.
      </td>
    </tr>

    <tr>
      <td>
        `voice_collection_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified voice collection does not exist.
      </td>
    </tr>

    {/* NOT_FOUND (404) - User/Account-related */}

    <tr>
      <td>
        `user_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified user was not found.
      </td>
    </tr>

    <tr>
      <td>
        `auth_account_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The authentication account was not found.
      </td>
    </tr>

    <tr>
      <td>
        `workspace_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified workspace does not exist.
      </td>
    </tr>

    {/* NOT_FOUND (404) - Content-related */}

    <tr>
      <td>
        `project_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified project was not found.
      </td>
    </tr>

    <tr>
      <td>
        `history_item_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified history item does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `collection_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified collection was not found.
      </td>
    </tr>

    <tr>
      <td>
        `document_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified document does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `file_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified file was not found.
      </td>
    </tr>

    {/* NOT_FOUND (404) - Feature-specific */}

    <tr>
      <td>
        `conversation_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified conversation does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `agent_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified agent was not found.
      </td>
    </tr>

    <tr>
      <td>
        `dubbing_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified dubbing project does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `song_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified song was not found.
      </td>
    </tr>

    <tr>
      <td>
        `read_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified read was not found.
      </td>
    </tr>

    <tr>
      <td>
        `pronunciation_dictionary_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified pronunciation dictionary does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `knowledge_base_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified knowledge base was not found.
      </td>
    </tr>

    <tr>
      <td>
        `phone_number_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified phone number does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `tool_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified tool was not found.
      </td>
    </tr>

    <tr>
      <td>
        `snapshot_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified snapshot does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `task_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified task was not found.
      </td>
    </tr>

    <tr>
      <td>
        `model_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified model does not exist.
      </td>
    </tr>

    <tr>
      <td>
        `transcript_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified transcript was not found.
      </td>
    </tr>

    <tr>
      <td>
        `keywords_list_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified keywords list was not found.
      </td>
    </tr>

    <tr>
      <td>
        `category_not_found`
      </td>

      <td>
        `not_found`
      </td>

      <td>
        The specified category was not found.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Text/Input validation */}

    <tr>
      <td>
        `text_too_long`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The provided text exceeds the maximum allowed length.
      </td>
    </tr>

    <tr>
      <td>
        `text_too_short`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The provided text is shorter than the minimum required length.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_text`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The provided text contains invalid characters or formatting.
      </td>
    </tr>

    <tr>
      <td>
        `empty_text`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The text field cannot be empty.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Parameter validation */}

    <tr>
      <td>
        `invalid_parameters`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        One or more request parameters are invalid. Check the `param` property for the invalid
        parameter.
      </td>
    </tr>

    <tr>
      <td>
        `missing_required_field`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        A required field is missing from the request. Check the `param` property for the missing
        field.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Voice settings */}

    <tr>
      <td>
        `invalid_voice_settings`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The voice settings contain invalid values. Check the `param` property for the invalid voice
        settings.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_voice_id`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The voice ID format is invalid.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Model settings */}

    <tr>
      <td>
        `unsupported_model`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The specified model is not supported for this operation.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Audio/Media validation */}

    <tr>
      <td>
        `invalid_audio`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The provided audio is invalid or corrupted.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_audio_format`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The specified audio format is not supported.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_output_format`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The requested output format is not supported.
      </td>
    </tr>

    <tr>
      <td>
        `audio_too_long`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The audio exceeds the maximum allowed duration.
      </td>
    </tr>

    <tr>
      <td>
        `audio_too_short`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The audio is shorter than the minimum required duration.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_file_type`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The file type is not supported.
      </td>
    </tr>

    {/* VALIDATION_ERROR (400) - Pagination/Query */}

    <tr>
      <td>
        `invalid_page_size`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The page size parameter is outside the allowed range.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_cursor`
      </td>

      <td>
        `validation_error`
      </td>

      <td>
        The pagination cursor is invalid or expired.
      </td>
    </tr>

    {/* INVALID_REQUEST (400) */}

    <tr>
      <td>
        `bad_request`
      </td>

      <td>
        `invalid_request`
      </td>

      <td>
        The request could not be understood by the server.
      </td>
    </tr>

    <tr>
      <td>
        `malformed_json`
      </td>

      <td>
        `invalid_request`
      </td>

      <td>
        The request body contains invalid JSON.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_content_type`
      </td>

      <td>
        `invalid_request`
      </td>

      <td>
        The Content-Type header is missing or invalid.
      </td>
    </tr>

    <tr>
      <td>
        `request_too_large`
      </td>

      <td>
        `invalid_request`
      </td>

      <td>
        The request body exceeds the maximum allowed size.
      </td>
    </tr>

    {/* AUTHENTICATION_ERROR (401) */}

    <tr>
      <td>
        `invalid_api_key`
      </td>

      <td>
        `authentication_error`
      </td>

      <td>
        The provided API key is invalid.
      </td>
    </tr>

    <tr>
      <td>
        `missing_api_key`
      </td>

      <td>
        `authentication_error`
      </td>

      <td>
        No API key was provided in the request.
      </td>
    </tr>

    <tr>
      <td>
        `invalid_authorization_header`
      </td>

      <td>
        `authentication_error`
      </td>

      <td>
        The Authorization header format is invalid.
      </td>
    </tr>

    <tr>
      <td>
        `unauthorized`
      </td>

      <td>
        `authentication_error`
      </td>

      <td>
        Authentication is required to access this resource.
      </td>
    </tr>

    <tr>
      <td>
        `sign_in_required`
      </td>

      <td>
        `authentication_error`
      </td>

      <td>
        You must be signed in to perform this action.
      </td>
    </tr>

    {/* AUTHORIZATION_ERROR (403) */}

    <tr>
      <td>
        `forbidden`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        Access to this resource is forbidden.
      </td>
    </tr>

    <tr>
      <td>
        `insufficient_permissions`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        You do not have the required permissions for this action.
      </td>
    </tr>

    <tr>
      <td>
        `workspace_access_denied`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        You do not have access to this workspace.
      </td>
    </tr>

    <tr>
      <td>
        `feature_not_available`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        This feature is not available on your current plan.
      </td>
    </tr>

    <tr>
      <td>
        `subscription_required`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        A paid subscription is required to access this feature.
      </td>
    </tr>

    <tr>
      <td>
        `voice_access_denied`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        You do not have access to this voice.
      </td>
    </tr>

    <tr>
      <td>
        `model_access_denied`
      </td>

      <td>
        `authorization_error`
      </td>

      <td>
        You do not have access to this model.
      </td>
    </tr>

    {/* CONFLICT (409) */}

    <tr>
      <td>
        `conflict`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        A conflict occurred.
      </td>
    </tr>

    <tr>
      <td>
        `resource_already_exists`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        A resource with the same identifier already exists.
      </td>
    </tr>

    <tr>
      <td>
        `voice_already_exists`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        A voice with this name already exists.
      </td>
    </tr>

    <tr>
      <td>
        `already_running`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        The operation is already running.
      </td>
    </tr>

    <tr>
      <td>
        `already_processing`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        The resource is already being processed.
      </td>
    </tr>

    <tr>
      <td>
        `concurrent_modification`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        The resource was modified by another request. Retry with the latest version.
      </td>
    </tr>

    <tr>
      <td>
        `slug_already_exists`
      </td>

      <td>
        `conflict`
      </td>

      <td>
        A resource with this slug already exists.
      </td>
    </tr>

    {/* RATE_LIMIT_ERROR (429) */}

    <tr>
      <td>
        `rate_limit_exceeded`
      </td>

      <td>
        `rate_limit_error`
      </td>

      <td>
        Too many requests. Wait before retrying.
      </td>
    </tr>

    <tr>
      <td>
        `concurrent_limit_exceeded`
      </td>

      <td>
        `rate_limit_error`
      </td>

      <td>
        Maximum number of concurrent requests exceeded. Higher subscription tiers have a higher
        concurrency limit.
      </td>
    </tr>

    <tr>
      <td>
        `system_busy`
      </td>

      <td>
        `rate_limit_error`
      </td>

      <td>
        The system is currently busy. Try again later.
      </td>
    </tr>

    {/* PAYMENT_REQUIRED (402) */}

    <tr>
      <td>
        `insufficient_credits`
      </td>

      <td>
        `payment_required`
      </td>

      <td>
        Your account does not have enough credits for this operation.
      </td>
    </tr>

    {/* INTERNAL_ERROR (500) */}

    <tr>
      <td>
        `internal_error`
      </td>

      <td>
        `internal_error`
      </td>

      <td>
        An unexpected error occurred. Contact support if this persists.
      </td>
    </tr>

    {/* SERVICE_UNAVAILABLE (503) */}

    <tr>
      <td>
        `service_unavailable`
      </td>

      <td>
        `service_unavailable`
      </td>

      <td>
        The service is temporarily unavailable. Try again later.
      </td>
    </tr>

    <tr>
      <td>
        `maintenance`
      </td>

      <td>
        `service_unavailable`
      </td>

      <td>
        The service is undergoing scheduled maintenance.
      </td>
    </tr>
  </tbody>
</table>


# Agent Tooling

> Tools for agents to build with ElevenLabs.

## Overview

Agent tooling includes reusable skills and local integrations that help you automate ElevenLabs workflows in developer tools and assistants.

## Agent skills

Agent Skills are reusable building blocks for common ElevenLabs workflows. They follow the Agent Skills specification and can be used with compatible coding assistants. Install the skills with:

```bash
npx skills add elevenlabs/skills
```

The official collection is hosted in the [elevenlabs/skills](https://github.com/elevenlabs/skills) repository.
Open each skill for a prompt you can paste into your assistant after installing the skills.

<AccordionGroup>
  <Accordion title="Text to speech">
    Convert text to speech using ElevenLabs voices.

    ```text
    Use the text to speech skill to generate audio for the script below.
    Model: eleven_v3
    Voice: "Juniper" (or default).
    Output: Save the MP3 file locally and return the file path.
    Script: "Welcome to ElevenLabs. Today we will walk through the new agent tooling."
    ```
  </Accordion>

  <Accordion title="Speech to text">
    Transcribe audio to text with timestamps.

    ```text
    Use the speech to text skill to transcribe the audio file path/to/file.mp3.
    Return a transcript that contains speaker IDs and timestamps at the start of each paragraph.
    ```
  </Accordion>

  <Accordion title="Realtime speech to text">
    Stream live transcription with low latency.

    ```text
    Use the speech to text skill to start a real-time transcription session for microphone input.
    Model: scribe_v2_realtime.
    Stream partial transcripts and return committed transcripts with word-level timestamps.
    ```
  </Accordion>

  <Accordion title="Agents">
    Build conversational voice agents.

    ```text
    Use the Agents skill to create a voice agent named "Support Concierge".
    Persona: friendly, concise, asks clarifying questions when needed.
    Goals: answer pricing questions and route enterprise leads to sales.
    ```
  </Accordion>

  <Accordion title="Sound effects">
    Generate sound effects from text prompts.

    ```text
    Use the Sound effects skill to generate a 3-second effect: "Wooden door creaks open, then a soft slam."
    Output WAV at 48 kHz and return the file path.
    ```
  </Accordion>

  <Accordion title="Music">
    Generate music tracks from prompts.

    ```text
    Use the Music skill to generate a 30-second instrumental loop.
    Style: lo-fi hip hop, warm, chill.
    BPM: 80. No vocals.
    Return the audio file path.
    ```
  </Accordion>

  <Accordion title="Setup API key">
    Get and configure an ElevenLabs API key.

    ```text
    How do I get my ElevenLabs API key?
    ```
  </Accordion>
</AccordionGroup>

## ElevenLabs MCP server

The ElevenLabs MCP server is a local Model Context Protocol server for the ElevenLabs platform. It runs on your machine so tools like Claude and Cursor can call ElevenLabs APIs through simple prompts.

<CardGroup>
  <Card title="ElevenLabs MCP" icon="plug" href="https://github.com/elevenlabs/elevenlabs-mcp">
    Install and run the MCP server locally.
  </Card>
</CardGroup>


# Zero Retention Mode (Enterprise)

> Learn how to use Zero Retention Mode to protect sensitive data.

## Background

By default, ElevenLabs retains data, in accordance with the Privacy Policy, to enhance services, troubleshoot issues, and ensure the security of ElevenLabs'systems. However, for some enterprise customers, ElevenLabs offers a "Zero Retention Mode" option for specific products. In this Zero Retention Mode, most data in requests and responses are immediately deleted once the request is completed.

ElevenLabs has agreements in place with each third-party LLM provider which expressly prohibit such providers from training their models on customer content, whether or not Zero Retention Mode is enabled.

## What is Zero Retention Mode?

Zero Retention Mode provides an additional level of security and peace of mind for especially sensitive workflows. When enabled, logging of certain data points is restricted, including:

* TTS text input
* TTS audio output
* Voice Changer audio input
* Voice Changer audio output
* STT audio input
* STT text output
* ElevenLabs Agents: all input and output
* Email associated with the account generating the input in our logs

This data is related to the processing of the request, and can only be seen by the user doing the request and the volatile memory of the process serving the request. None of this data is sent at any point to a database where data is stored long term.

## Who has access to Zero Retention Mode?

Enterprise customers can use Zero Retention Mode. It is primarily intended for use by our customers in the healthcare and banking sector, and other customers who may use our services to process sensitive information.

## When can a customer use Zero Retention Mode?

Zero Retention Mode is available to select enterprise customers. However, access to this feature may be restricted if ElevenLabs determines a customer's use case to be high risk, if an account is flagged by an automated system for additional moderation or at ElevenLabs' sole discretion. In such cases, the enterprise administrator will be promptly notified of the restriction.

## How does Zero Retention Mode work?

Zero Retention Mode only works for API requests, specifically:

* **Text to Speech**: this covers the Text-to-Speech (TTS) API, including all endpoints beginning with `/v1/text-to-speech/` and the TTS websocket connection.
* **Voice Changer**: this covers the Voice Changer API, including all endpoints starting with `/v1/speech-to-speech/`.

After setup, check the request history to verify Zero Retention Mode is enabled. If enabled, there should be no requests in the history.

Zero Retention Mode can be used by sending `enable_logging=false` with the product which supports it.

For example, in the Text to Speech API, you can set the query parameter [enable\_logging](https://elevenlabs.io/docs/api-reference/text-to-speech#parameter-enable-logging) to a `false` value:

<CodeBlocks>
  ```python title="Python" {12}
  from elevenlabs import ElevenLabs

  elevenlabs = ElevenLabs(
    api_key="YOUR_API_KEY",
  )

  response = elevenlabs.text_to_speech.convert(
    voice_id=voice_id,
    output_format="mp3_22050_32",
    text=text,
    model_id="eleven_turbo_v2",
    enable_logging=False,
  )

  ```

  ```javascript title="JavaScript" {9}
  import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

  const elevenlabs = new ElevenLabsClient({ apiKey: 'YOUR_API_KEY' });

  await elevenlabs.textToSpeech.convert(voiceId, {
    outputFormat: 'mp3_44100_128',
    text: text,
    modelId: 'eleven_turbo_v2',
    enableLogging: false,
  });
  ```

  ```bash title="cURL"
  curl --request POST \
    --url 'https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?enable_logging=false' \
    --header 'Content-Type: application/json'
  ```
</CodeBlocks>

## What products are configured for Zero Retention Mode?

| Product                    | Type                 | Default Retention | Eligible for Zero Retention |
| -------------------------- | -------------------- | ----------------- | --------------------------- |
| Text to Speech             | Text Input           | Enabled           | Yes                         |
|                            | Audio Output         | Enabled           | Yes                         |
| Voice Changer              | Audio Input          | Enabled           | Yes                         |
|                            | Audio Output         | Enabled           | Yes                         |
| Speech to Text             | Audio Input          | Enabled           | Yes                         |
|                            | Text Output          | Enabled           | Yes                         |
| Music                      | Text Input           | Enabled           | No                          |
|                            | Audio Output         | Enabled           | No                          |
| Image & Video              | All Input and Output | Enabled           | No                          |
| Instant Voice Cloning      | Audio Samples        | Enabled           | No                          |
| Professional Voice Cloning | Audio Samples        | Enabled           | No                          |
| Dubbing                    | Audio/Video Input    | Enabled           | No                          |
|                            | Audio Output         | Enabled           | No                          |
| Studio                     | Text Input           | Enabled           | No                          |
|                            | Audio Output         | Enabled           | No                          |
| Agents Platform            | All Input and Output | Enabled           | Yes                         |

For ElevenLabs Agents, Gemini and Claude LLMs can be used in Zero Retention Mode.

## FAQ

<AccordionGroup>
  <Accordion title="What are some limitations of Zero Retention Mode?" default>
    Troubleshooting and support for Zero Retention Mode is limited. Because of the configuration, we
    will not be able to diagnose issues with TTS/STS generations. Debugging will be more difficult
    as a result.
  </Accordion>

  <Accordion title="How does retention work if Zero Retention Mode is not active?">
    Customers by default have history preservation enabled. All customers can use the API to delete
    generations at any time. This action will immediately remove the corresponding audio and text
    from our database; however, debugging and moderation logs may still retain data related to the
    generation.
  </Accordion>

  <Accordion title="Data backup (When Zero Retention Mode is not used)">
    For any retained data, we regularly back up such data to prevent data loss in the event of any
    unexpected incidents. Following data deletion, database items are retained in backups for up to
    30 days After this period, the data expires and is not recoverable.
  </Accordion>

  <Accordion title="Account deletion (When Zero Retention Mode is not used)">
    All data is deleted from our systems permanently when you delete your account. This includes all
    data associated with your account, such as API keys, request history, and any other data stored
    in your account. We also take commercially reasonable efforts to delete debugging data related
    to your account.
  </Accordion>
</AccordionGroup>


# Generate audio in real-time

> Learn how to generate audio in real-time via a WebSocket connection.

WebSocket streaming is a method of sending and receiving data over a single, long-lived connection. This method is useful for real-time applications where you need to stream audio data as it becomes available.

If you want to quickly test out the latency (time to first byte) of a WebSocket connection to the ElevenLabs text-to-speech API, you can install `elevenlabs-latency` via `npm` and follow the instructions [here](https://www.npmjs.com/package/elevenlabs-latency?activeTab=readme).

<Note>
  WebSockets can be used with the Text to Speech and Agents Platform products. This guide will
  demonstrate how to use them with the Text to Speech API. WebSockets are not available for the
  `eleven_v3` model.
</Note>

## Requirements

* An ElevenLabs account with an API key (here’s how to [find your API key](/docs/api-reference/authentication)).
* Python or Node.js (or another JavaScript runtime) installed on your machine

## Setup

Install required dependencies:

<CodeBlocks>
  ```python Python
  pip install python-dotenv
  pip install websockets
  ```

  ```typescript TypeScript
  npm install dotenv
  npm install @types/dotenv --save-dev
  npm install ws
  ```
</CodeBlocks>

Next, create a `.env` file in your project directory and add your API key:

```bash .env
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
```

## Initiate the websocket connection

After choosing a voice from the Voice Library and the text to speech model you wish to use, initiate a WebSocket connection to the text to speech API.

<CodeBlocks>
  ```python text-to-speech-websocket.py
  import os
  from dotenv import load_dotenv
  import websockets

  # Load the API key from the .env file
  load_dotenv()
  ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")

  voice_id = 'Xb7hH8MSUJpSbSDYk0k2'

  # For use cases where latency is important, we recommend using the 'eleven_flash_v2_5' model.
  model_id = 'eleven_flash_v2_5'

  async def text_to_speech_ws_streaming(voice_id, model_id):
      uri = f"wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input?model_id={model_id}"

      async with websockets.connect(uri) as websocket:
         ...
  ```

  ```typescript text-to-speech-websocket.ts
  import * as dotenv from 'dotenv';
  import * as fs from 'node:fs';
  import WebSocket from 'ws';

  // Load the API key from the .env file
  dotenv.config();
  const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

  const voiceId = 'Xb7hH8MSUJpSbSDYk0k2';

  // For use cases where latency is important, we recommend using the 'eleven_flash_v2_5' model.
  const model = 'eleven_flash_v2_5';

  const uri = `wss://api.elevenlabs.io/v1/text-to-speech/${voiceId}/stream-input?model_id=${model}`;
  const websocket = new WebSocket(uri, {
    headers: { 'xi-api-key': `${ELEVENLABS_API_KEY}` },
  });

  // Create a directory for saving the audio
  const outputDir = './output';

  try {
    fs.accessSync(outputDir, fs.constants.R_OK | fs.constants.W_OK);
  } catch (err) {
    fs.mkdirSync(outputDir);
  }

  // Create a write stream for saving the audio into mp3
  const writeStream = fs.createWriteStream(outputDir + '/test.mp3', {
    flags: 'a',
  });
  ```
</CodeBlocks>

## Send the input text

Once the WebSocket connection is open, set up voice settings first. Next, send the text message to the API.

<CodeBlocks>
  ```python text-to-speech-websocket.py
  async def text_to_speech_ws_streaming(voice_id, model_id):
      async with websockets.connect(uri) as websocket:
          await websocket.send(json.dumps({
              "text": " ",
              "voice_settings": {"stability": 0.5, "similarity_boost": 0.8, "use_speaker_boost": False},
              "generation_config": {
                  "chunk_length_schedule": [120, 160, 250, 290]
              },
              "xi_api_key": ELEVENLABS_API_KEY,
          }))

          text = "The twilight sun cast its warm golden hues upon the vast rolling fields, saturating the landscape with an ethereal glow. Silently, the meandering brook continued its ceaseless journey, whispering secrets only the trees seemed privy to."
          await websocket.send(json.dumps({"text": text}))

          // Send empty string to indicate the end of the text sequence which will close the WebSocket connection
          await websocket.send(json.dumps({"text": ""}))
  ```

  ```typescript text-to-speech-websocket.ts
  const text =
    'The twilight sun cast its warm golden hues upon the vast rolling fields, saturating the landscape with an ethereal glow. Silently, the meandering brook continued its ceaseless journey, whispering secrets only the trees seemed privy to.';

  websocket.on('open', async () => {
    websocket.send(
      JSON.stringify({
        text: ' ',
        voice_settings: {
          stability: 0.5,
          similarity_boost: 0.8,
          use_speaker_boost: false,
        },
        generation_config: { chunk_length_schedule: [120, 160, 250, 290] },
      })
    );

    websocket.send(JSON.stringify({ text: text }));

    // Send empty string to indicate the end of the text sequence which will close the websocket connection
    websocket.send(JSON.stringify({ text: '' }));
  });
  ```
</CodeBlocks>

## Save the audio to file

Read the incoming message from the WebSocket connection and write the audio chunks to a local file.

<CodeBlocks>
  ```python text-to-speech-websocket.py
  import asyncio

  async def write_to_local(audio_stream):
      """Write the audio encoded in base64 string to a local mp3 file."""

      with open(f'./output/test.mp3', "wb") as f:
          async for chunk in audio_stream:
              if chunk:
                  f.write(chunk)

  async def listen(websocket):
      """Listen to the websocket for audio data and stream it."""

      while True:
          try:
              message = await websocket.recv()
              data = json.loads(message)
              if data.get("audio"):
                  yield base64.b64decode(data["audio"])
              elif data.get('isFinal'):
                  break

          except websockets.exceptions.ConnectionClosed:
              print("Connection closed")
              break

  async def text_to_speech_ws_streaming(voice_id, model_id):
      async with websockets.connect(uri) as websocket:
            ...
            # Add listen task to submit the audio chunks to the write_to_local function
            listen_task = asyncio.create_task(write_to_local(listen(websocket)))

            await listen_task

  asyncio.run(text_to_speech_ws_streaming(voice_id, model_id))
  ```

  ```typescript text-to-speech-websocket.ts
  // Helper function to write the audio encoded in base64 string into local file
  function writeToLocal(base64str: any, writeStream: fs.WriteStream) {
    const audioBuffer: Buffer = Buffer.from(base64str, 'base64');
    writeStream.write(audioBuffer, (err) => {
      if (err) {
        console.error('Error writing to file:', err);
      }
    });
  }

  // Listen to the incoming message from the websocket connection
  websocket.on('message', function incoming(event) {
    const data = JSON.parse(event.toString());
    if (data['audio']) {
      writeToLocal(data['audio'], writeStream);
    }
  });

  // Close the writeStream when the websocket connection closes
  websocket.on('close', () => {
    writeStream.end();
  });
  ```
</CodeBlocks>

## Run the script

You can run the script by executing the following command in your terminal. An mp3 audio file will be saved in the `output` directory.

<CodeBlocks>
  ```python Python
  python text-to-speech-websocket.py
  ```

  ```typescript TypeScript
  npx tsx text-to-speech-websocket.ts
  ```
</CodeBlocks>

## Advanced configuration

The use of WebSockets comes with some advanced settings that you can use to fine-tune your real-time audio generation.

### Buffering

When generating real-time audio, two important concepts should be taken into account: Time To First Byte (TTFB) and Buffering. To produce high quality audio and deduce context, the model requires a certain threshold of input text. The more text that is sent in a WebSocket connection, the better the audio quality. If the threshold is not met, the model will add the text to a buffer and generate audio once the buffer is full.

In terms of latency, TTFB is the time it takes for the first byte of audio to be sent to the client. This is important because it affects the perceived latency of the audio. As such, you might want to control the buffer size to balance between quality and latency.

To manage this, you can use the `chunk_length_schedule` parameter when either initializing the WebSocket connection or when sending text. This parameter is an array of integers that represent the number of characters that will be sent to the model before generating audio. For example, if you set `chunk_length_schedule` to `[120, 160, 250, 290]`, the model will generate audio after 120, 160, 250, and 290 characters have been sent, respectively.

Here's an example of how this works with the default settings for `chunk_length_schedule`:

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/077efc232570b0f92355aed2d6766b66bba815e335466e81cd64f8dfcce10ada/assets/images/developer-guides/buffering-explainer.jpg" />

In the above diagram, audio is only generated after the second message is sent to the server. This is because the first message is below the threshold of 120 characters, while the second message brings the total number of characters above the threshold. The third message is above the threshold of 160 characters, so audio is immediately generated and returned to the client.

You can specify a custom value for `chunk_length_schedule` when initializing the WebSocket connection or when sending text.

<CodeBlocks>
  ```python
  await websocket.send(json.dumps({
      "text": text,
      "generation_config": {
          # Generate audio after 50, 120, 160, and 290 characters have been sent
          "chunk_length_schedule": [50, 120, 160, 290]
      },
      "xi_api_key": ELEVENLABS_API_KEY,
  }))
  ```

  ```typescript
  websocket.send(
    JSON.stringify({
      text: text,
      // Generate audio after 50, 120, 160, and 290 characters have been sent
      generation_config: { chunk_length_schedule: [50, 120, 160, 290] },
      xi_api_key: ELEVENLABS_API_KEY,
    })
  );
  ```
</CodeBlocks>

In the case that you want force the immediate return of the audio, you can use `flush: true` to clear out the buffer and force generate any buffered text. This can be useful, for example, when you have reached the end of a document and want to generate audio for the final section.

<img src="https://files.buildwithfern.com/https://elevenlabs.docs.buildwithfern.com/docs/84011e01024effe1bba1556f0007c7947165a0101bce3a41f8b955d1a9788a9c/assets/images/developer-guides/buffering-flush-explainer.jpg" />

This can be specified on a per-message basis by setting `flush: true` in the message.

<CodeBlocks>
  ```python
  await websocket.send(json.dumps({"text": "Generate this audio immediately.", "flush": True}))
  ```

  ```typescript
  websocket.send(JSON.stringify({ text: 'Generate this audio immediately.', flush: true }));
  ```
</CodeBlocks>

In addition, closing the websocket will automatically force generate any buffered text.

### Voice settings

When initializing the WebSocket connections, you can specify the voice settings for the subsequent generations. This allows you to control the speed, stability, and other voice characteristics of the generated audio.

<CodeBlocks>
  ```python
  await websocket.send(json.dumps({
      "text": text,
      "voice_settings": {"stability": 0.5, "similarity_boost": 0.8, "use_speaker_boost": False},
  }))
  ```

  ```typescript
  websocket.send(
    JSON.stringify({
      text: text,
      voice_settings: { stability: 0.5, similarity_boost: 0.8, use_speaker_boost: false },
    })
  );
  ```
</CodeBlocks>

This can be overridden on a per-message basis by specifying a different `voice_settings` in the message.

### Pronunciation dictionaries

You can use pronunciation dictionaries to control the pronunciation of specific words or phrases. This can be useful for ensuring that certain words are pronounced correctly or for adding emphasis to certain words or phrases.

Unlike `voice_settings` and `generation_config`, pronunciation dictionaries must be specified in the "Initialize Connection" message. See the [API Reference](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-stream-input#send.Initialize%20Connection.pronunciation_dictionary_locators) for more information.

<Tip>
  When using phoneme-based pronunciation dictionaries with WebSockets, you must add `enable_ssml_parsing=true` as a query parameter to the WebSocket URI. For example:

  ```
  wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input?model_id={model_id}&enable_ssml_parsing=true
  ```
</Tip>

## Best practice

* We suggest using the default setting for `chunk_length_schedule` in `generation_config`.
* When developing a real-time conversational agent application, we advise using `flush: true` along with the text at the end of conversation turn to ensure timely audio generation.
* If the default setting doesn't provide optimal latency for your use case, you can modify the `chunk_length_schedule`. However, be mindful that reducing latency through this adjustment may come at the expense of quality.

## Tips

* The WebSocket connection will automatically close after 20 seconds of inactivity. To keep the connection open, you can send a single space character `" "`. Please note that this string must include a space, as sending a fully empty string, `""`, will close the WebSocket.
* Send an empty string to close the WebSocket connection after sending the last text message.
* You can use `alignment` to get the word-level timestamps for each word in the text. This can be useful for aligning the audio with the text in a video or for other applications that require precise timing. See the [API Reference](/docs/api-reference/text-to-speech/v-1-text-to-speech-voice-id-stream-input#receive.Audio%20Output.alignment) for more information.


# Migrate from PlayHT to ElevenLabs

> Migrate your PlayHT voice generation and Text To Speech workflows to ElevenLabs.

ElevenLabs provides a seamless migration path for PlayHT users. This guide will walk you through the steps to migrate your PlayHT voice generation and Text To Speech workflows to ElevenLabs.

The ElevenLabs API provides a simple interface to state-of-the-art audio [models](/docs/overview/models) and [features](/docs/api-reference/introduction). Follow this guide to learn how to create lifelike speech with our Text to Speech API. See the [developer guides](/docs/developers/quickstart#explore-our-developer-guides) for more examples with our other products.

## Using the Text to Speech API

<Steps>
  <Step title="Create an API key">
    [Create an API key in the dashboard here](https://elevenlabs.io/app/settings/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

    Store the key as a managed secret and pass it to the SDKs either as a environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

    ```js title=".env"
    ELEVENLABS_API_KEY=<your_api_key_here>
    ```
  </Step>

  <Step title="Install the SDK">
    We'll also use the `dotenv` library to load our API key from an environment variable.

    <CodeBlocks>
      ```python
      pip install elevenlabs
      pip install python-dotenv
      ```

      ```typescript
      npm install @elevenlabs/elevenlabs-js
      npm install dotenv
      ```
    </CodeBlocks>

    <Note>
      To play the audio through your speakers, you may be prompted to install [MPV](https://mpv.io/)
      and/or [ffmpeg](https://ffmpeg.org/).
    </Note>
  </Step>

  <Step title="Make your first request">
    Create a new file named `example.py` or `example.mts`, depending on your language of choice and add the following code:

    {/* This snippet was auto-generated */}

    <CodeBlocks>
      ```python
      from dotenv import load_dotenv
      from elevenlabs.client import ElevenLabs
      from elevenlabs.play import play
      import os

      load_dotenv()

      elevenlabs = ElevenLabs(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
      )

      audio = elevenlabs.text_to_speech.convert(
          text="The first move is what sets everything in motion.",
          voice_id="JBFqnCBsd6RMkjVDRZzb",
          model_id="eleven_multilingual_v2",
          output_format="mp3_44100_128",
      )

      play(audio)

      ```

      ```typescript
      import { ElevenLabsClient, play } from '@elevenlabs/elevenlabs-js';
      import { Readable } from 'stream';
      import 'dotenv/config';

      const elevenlabs = new ElevenLabsClient();
      const audio = await elevenlabs.textToSpeech.convert('JBFqnCBsd6RMkjVDRZzb', {
        text: 'The first move is what sets everything in motion.',
        modelId: 'eleven_multilingual_v2',
        outputFormat: 'mp3_44100_128',
      });

      const reader = audio.getReader();
      const stream = new Readable({
        async read() {
          const { done, value } = await reader.read();
          if (done) {
            this.push(null);
          } else {
            this.push(value);
          }
        },
      });

      await play(stream);

      ```
    </CodeBlocks>
  </Step>

  <Step title="Run the code">
    <CodeBlocks>
      ```python
      python example.py
      ```

      ```typescript
      npx tsx example.mts
      ```
    </CodeBlocks>

    You should hear the audio play through your speakers.
  </Step>
</Steps>

## Migrating additional features

### Instant Voice Cloning

[This guide](/developers/guides/cookbooks/voices/instant-voice-cloning) will show you how to create an Instant Voice Clone using the Clone Voice API. To create an Instant Voice Clone via the dashboard, refer to the [Instant Voice Clone](/docs/creative-platform/voices/voice-cloning/instant-voice-cloning) product guide.

### Voice agents

ElevenLabs Agents lets you deploy customized, conversational voice agents in minutes. See the [Agents Platform overview](/docs/agents-platform/overview) to learn how to migrate your PlayAI voice agents.

### Audio streaming with Twilio

ElevenLabs Agents provides a [native Twilio integration](/docs/agents-platform/phone-numbers/twilio-integration/native-integration) as well as integrations with other telephony providers like [Vonage](/docs/agents-platform/phone-numbers/telephony/vonage), [Telnyx](/docs/agents-platform/phone-numbers/telephony/telnyx), and [Plivo](/docs/agents-platform/phone-numbers/telephony/plivo). Or connect your existing phone system with ElevenLabs Agents using [SIP trunking](/docs/agents-platform/phone-numbers/sip-trunking).

### Input Streaming with LLMs

In most cases you will want to use our end-to-end [Agents Platform](https://elevenlabs.io/conversational-ai). For advanced enterprise use cases you can use our [multi-context websocket](/developers/guides/cookbooks/multi-context-web-socket)

## Explore our developer guides

Now that you've made your first ElevenLabs API request, you can explore the other products that ElevenLabs offers.

<CardGroup cols={2}>
  <Card title="Speech to Text" icon="duotone pen-clip" href="/docs/developers/guides/cookbooks/speech-to-text/quickstart">
    Convert spoken audio into text
  </Card>

  <Card title="Music" icon="duotone music" href="/docs/developers/guides/cookbooks/music/quickstart">
    Generate studio-quality music
  </Card>

  <Card title="Text to Dialogue" icon="duotone comment-dots" href="/docs/developers/guides/cookbooks/text-to-dialogue">
    Create natural-sounding dialogue from text
  </Card>

  <Card title="Voice Changer" icon="duotone message-pen" href="/docs/developers/guides/cookbooks/voice-changer">
    Transform the voice of an audio file
  </Card>

  <Card title="Voice Isolator" icon="duotone ear" href="/docs/developers/guides/cookbooks/voice-isolator">
    Isolate background noise from audio
  </Card>

  <Card title="Dubbing" icon="duotone language" href="/docs/developers/guides/cookbooks/dubbing">
    Dub audio/video from one language to another
  </Card>

  <Card title="Sound Effects" icon="duotone explosion" href="/docs/developers/guides/cookbooks/sound-effects">
    Generate sound effects from text
  </Card>

  <Card title="Voice Cloning" icon="duotone clone" href="/docs/developers/guides/cookbooks/voices/instant-voice-cloning">
    Clone a voice
  </Card>

  <Card title="Voice Remixing" icon="duotone shuffle" href="/docs/developers/guides/cookbooks/voices/remix-a-voice">
    Remix a voice
  </Card>

  <Card title="Voice Design" icon="duotone paint-brush" href="/docs/developers/guides/cookbooks/voices/voice-design">
    Generate voices from a single text prompt
  </Card>

  <Card title="Forced Alignment" icon="duotone objects-align-left" href="/docs/developers/guides/cookbooks/forced-alignment">
    Generate time-aligned transcripts for audio
  </Card>

  <Card title="ElevenLabs Agents" icon="duotone comments" href="/docs/agents-platform/quickstart">
    Deploy conversational voice agents
  </Card>
</CardGroup>


# Latency optimization

> Learn how to optimize text-to-speech latency.

This guide covers the core principles for improving text-to-speech latency.

While there are many individual techniques, we'll group them into **four principles**.

<h4>
  Four principles
</h4>

1. [Use Flash models](#use-flash-models)
2. [Leverage streaming](#leverage-streaming)
3. [Consider geographic proximity](#consider-geographic-proximity)
4. [Choose appropriate voices](#choose-appropriate-voices)

<Success>
  Enterprise customers benefit from increased concurrency limits and priority access to our rendering queue. [Contact sales](https://elevenlabs.io/contact-sales) to learn more about our enterprise
  plans.
</Success>

## Use Flash models

[Flash models](/docs/overview/models#flash-v25) deliver \~75ms inference speeds, making them ideal for real-time applications. The trade-off is a slight reduction in audio quality compared to [Multilingual v2](/docs/overview/models#multilingual-v2).

<Info>
  75ms refers to model inference time only. Actual end-to-end latency will vary with factors such as
  your location & endpoint type used.
</Info>

## Leverage streaming

There are three types of text-to-speech endpoints available in our [API Reference](/docs/api-reference/introduction):

* **Regular endpoint**: Returns a complete audio file in a single response.
* **Streaming endpoint**: Returns audio chunks progressively using [Server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events).
* **Websockets endpoint**: Enables bidirectional streaming for real-time audio generation.

### Streaming

Streaming endpoints progressively return audio as it is being generated in real-time, reducing the time-to-first-byte. This endpoint is recommended for cases where the input text is available up-front.

<Info>
  Streaming is supported for the [Text to Speech](/docs/api-reference/text-to-speech/stream) API,
  [Voice Changer](/docs/api-reference/speech-to-speech/stream) API & [Audio
  Isolation](/docs/api-reference/audio-isolation/stream) API.
</Info>

### Websockets

The [text-to-speech websocket endpoint](/docs/api-reference#text-to-speech-websocket) supports bidirectional streaming making it perfect for applications with real-time text input (e.g. LLM outputs).

<Tip>
  Setting `auto_mode` to true automatically handles generation triggers, removing the need to
  manually manage chunk strategies.
</Tip>

If `auto_mode` is disabled, the model will wait for enough text to match the chunk schedule before starting to generate audio.

For instance, if you set a chunk schedule of 125 characters but only 50 arrive, the model stalls until additional characters come in—potentially increasing latency.

For implementation details, see the [text-to-speech websocket guide](/docs/api-reference#text-to-speech-websocket).

## Choose appropriate voices

We have observed that in some cases, voice selection can impact latency. Here's the order from fastest to slowest:

1. Default voices (formerly premade), Synthetic voices, and Instant Voice Clones (IVC)
2. Professional Voice Clones (PVC)

Higher audio quality output formats can increase latency. Be sure to balance your latency requirements with audio fidelity needs.

<Info>
  We are actively working on optimizing PVC latency for Flash v2.5.
</Info>

## Consider geographic proximity

We serve our models from multiple regions to optimize latency based on your geographic location.

You can check which backend region is serving your request by inspecting the `x-region` header in the API response.
Currently used regions include: USA, Netherlands and Singapore.

<Info>
  Enterprise customers can use our dedicated EU and India data residency environments for guarantees
  about the server location as well as low latency. Contact your sales representative to get
  onboarded to our data residency infrastructure.
</Info>

To opt-out of the global routing and always use USA servers, use the `api.us.elevenlabs.io` base URL for your API requests:

<CodeBlocks>
  ```python
  import os
  from elevenlabs.client import ElevenLabs

  elevenlabs = ElevenLabs(
      api_key=os.getenv("ELEVENLABS_API_KEY"),
      base_url="https://api.us.elevenlabs.io"
  )

  ```

  ```typescript
  import { ElevenLabs } from '@elevenlabs/elevenlabs-js';
  import 'dotenv/config';

  const elevenlabs = new ElevenLabs({
    apiKey: process.env.ELEVENLABS_API_KEY,
    baseUrl: 'https://api.us.elevenlabs.io',
  });
  ```

  ```bash cURL
  curl -X POST -v "https://api.us.elevenlabs.io/v1/text-to-speech/{voice_id}" \
    -H "Accept: audio/mpeg" \
    -H "Content-Type: application/json" \
    -H "xi-api-key: YOUR_API_KEY" \
    -d '{
      "text": "Hello World!",
      "model_id": "eleven_flash_v2_5"
    }'
  ```
</CodeBlocks>

<Warning>
  The global servers were previously opt-in using the `api-global-preview.elevenlabs.io` base URL.
  This is no longer necessary as it is now the default behavior. Please update your applications to
  simply use `api.elevenlabs.io` instead.
</Warning>


# Secure by design

> Learn how to safely integrate ElevenLabs APIs.

Whether you're building voicemail apps, interactive characters, or audio-driven games, the ElevenLabs API gives you direct access to powerful voice capabilities.
But with that access comes the responsibility to secure your users’ data and manage voice resources carefully.

This guide outlines two critical security practices for developers:

* Isolating environments using **service accounts**
* Implementing **resource-level permissions**

## Use service accounts to isolate environments

Service accounts provide scoped, API-only access to the ElevenLabs platform. Unlike user accounts, they’re not tied to individuals—they’re designed for backend systems and automation.

If a service account creates a resource, only admins can see it by default but it can be shared with other users. Similarly, you can share any resource with a service account just as you would with a user.
Each service account is created at the workspace level and managed by workspace admins. They can create and access resources through the API.

We recommend provisioning a dedicated service account for each environment:

* `production-service-account`
* `testing-service-account`
* `uat-service-account` (if applicable)

This ensures clean separation between environments, reduces accidental data leaks across environments, and simplifies monitoring.

### Why this matters

**Separation of concerns**\
Avoid mixing test and production data. Environment isolation supports auditability and compliance.

**Principle of least privilege**\
Each service account should only have access to the minimum necessary resources. API keys can be scoped further at the time of creation.

**Better observability**\
Track API usage and performance by environment. Separate service accounts make it easier to debug issues and monitor activity.

## Apply resource-level permissions in your backend

If your app allows users to record messages using cloned voices, it is essential to ensure users only access voices they own or have been granted permission to use.

While the ElevenLabs platform supports in-app sharing, you should enforce **resource-level access control** within your own systems when using the API.

A recommended model:

```
user_id | voice_id | permission_level
```

Possible permission\_level values:

* `viewer`: can use the voice for speech generation
* `editor`: can update voice settings
* `admin`: can manage sharing and permissions

This structure lets you control who can access and modify voices and prevents unauthorized use of sensitive resources.
These permissions are suggestions based on controls natively offered if you are directly using the ElevenLabs platform.

### Build securely. Scale confidently.

Security should be foundational, not an afterthought.
By leveraging service accounts and implementing permission controls, you’ll reduce risk and build trust—while giving your users the full potential of AI voice.


# Breaking changes policy

> Learn how ElevenLabs defines breaking changes in the APIs.

## Overview

In order to balance rapid development and maintaining stability, ElevenLabs has specific guidelines on what are considered breaking changes within the scope of the API. Outlined here are what we do and do not consider breaking changes.

<Note>
  All API updates and changes are published in the [changelog](/docs/changelog) on a weekly cadence.
</Note>

## Response and Schema Changes

We distinguish carefully between additive and subtractive changes to API responses. Adding new fields to response models is not considered breaking. When integrating with our API it is required that your API client ignores fields that they do not recognise and do not have strict typing checks for API responses. Almost all modern API clients do this out of the box.

Removing existing response fields or modifying their structure is breaking since client applications may depend on these fields being present and maintaining their expected format.

## Parameter Modifications

Changes to API parameters follow a strict compatibility model. Adding required parameters to existing endpoints is always breaking because existing client calls will fail validation. However, adding optional parameters (those with default values or explicitly marked as optional) is not breaking since existing client calls can continue without modification. Similarly, any changes to parameter types, formats, or making previously optional parameters required are considered breaking as they alter the contract that clients expect.

## Endpoint and Path Changes

Removing entire endpoints or API paths is inherently breaking since client applications calling these endpoints will receive errors. Endpoints might be marked as deprecated, however the outright removal of them will not occur without sufficient outreach to all affected users.


# Private deployment

> Deploy ElevenLabs Text to Speech models in your private cloud infrastructure for maximum security and control.

## Get Started

<Info>
  Private deployment documentation and technical resources are available to authorized enterprise
  customers.
</Info>

ElevenLabs is able to deploy its models through the AWS Marketplace and Amazon SageMaker, allowing enterprise customers to run Text to Speech models within their own secure cloud infrastructure.

<CardGroup cols={2}>
  <Card title="State-of-the-art models" icon="duotone waveform-lines">
    Access to ElevenLabs' v2 and v2.5 TTS models
  </Card>

  <Card title="Complete data control" icon="duotone database">
    All text and audio data remains within your infrastructure
  </Card>

  <Card title="Enhanced security" icon="duotone shield-check">
    Meet strict compliance and data residency requirements
  </Card>

  <Card title="Enterprise support" icon="duotone headset">
    Dedicated engineering support and guidance for your deployment
  </Card>
</CardGroup>

To learn more about private deployment options and get access to the technical documentation, contact your ElevenLabs account team or [reach out to our sales team](https://elevenlabs.io/contact-sales).


# Introduction

> Explore the ElevenLabs API reference with comprehensive guides, code examples, and endpoint documentation

## Installation

You can interact with the API through HTTP or Websocket requests from any language, via our official Python bindings or our official Node.js libraries.

To install the official Python bindings, run the following command:

```bash
pip install elevenlabs
```

To install the official Node.js library, run the following command in your Node.js project directory:

```bash
npm install @elevenlabs/elevenlabs-js
```

## Tracking generation costs

Access response headers to retrieve generation metadata including character costs.

<CodeBlocks>
  <CodeBlock title="Python">
    ```python
    from elevenlabs.client import ElevenLabs

    client = ElevenLabs(api_key="your_api_key")

    # Get raw response with headers
    response = client.text_to_speech.with_raw_response.convert(
        text="Hello, world!",
        voice_id="voice_id"
    )

    # Access character cost from headers
    char_cost = response.headers.get("x-character-count")
    request_id = response.headers.get("request-id")
    audio_data = response.data
    ```
  </CodeBlock>

  <CodeBlock title="JavaScript">
    ```typescript
    import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

    const client = new ElevenLabsClient({ apiKey: 'your_api_key' });

    // Get raw response with headers
    const { data, rawResponse } = await client.textToSpeech
      .convert('voice_id', {
        text: 'Hello, world!',
        modelId: 'eleven_multilingual_v2',
      })
      .withRawResponse();

    // Access character cost from headers
    const charCost = rawResponse.headers.get('x-character-count');
    const requestId = rawResponse.headers.get('request-id');
    const audioData = data;
    ```
  </CodeBlock>
</CodeBlocks>

The raw response provides access to:

* Response data - The actual API response content
* HTTP headers - Metadata including character costs and request IDs

<div id="overview-wave">
  <ElevenLabsWaveform color="gray" />
</div>


# API Authentication

> Learn how to authenticate your ElevenLabs API requests

## API Keys

The ElevenLabs API uses API keys for authentication. Every request to the API must include your API key, used to authenticate your requests and track usage quota.

Each API key can be scoped to one of the following:

1. **Scope restriction:** Set access restrictions by limiting which API endpoints the key can access.
2. **Credit quota:** Define custom credit limits to control usage.

**Remember that your API key is a secret.** Do not share it with others or expose it in any client-side code (browsers, apps).

All API requests should include your API key in an `xi-api-key` HTTP header as follows:

```bash
xi-api-key: ELEVENLABS_API_KEY
```

### Making requests

You can paste the command below into your terminal to run your first API request. Make sure to replace `$ELEVENLABS_API_KEY` with your secret API key.

```bash
curl 'https://api.elevenlabs.io/v1/models' \
  -H 'Content-Type: application/json' \
  -H 'xi-api-key: $ELEVENLABS_API_KEY'
```

Example with the `elevenlabs` Python package:

```python
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(
  api_key='YOUR_API_KEY',
)
```

Example with the `elevenlabs` Node.js package:

```javascript
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient({
  apiKey: 'YOUR_API_KEY',
});
```

### Single use tokens

For certain endpoints, you can use single use tokens to authenticate your requests. These tokens are valid for a limited time and can be used to connect to the API without exposing your API key, for example from the client side.

See the [Single use tokens](/docs/api-reference/tokens/create) documentation for more information.


# Streaming

> Learn how to stream real-time audio from the ElevenLabs API using chunked transfer encoding

The ElevenLabs API supports real-time audio streaming for select endpoints, returning raw audio bytes (e.g., MP3 data) directly over HTTP using chunked transfer encoding. This allows clients to process or play audio incrementally as it is generated.

Our official [Node](https://github.com/elevenlabs/elevenlabs-js) and [Python](https://github.com/elevenlabs/elevenlabs-python) libraries include utilities to simplify handling this continuous audio stream.

Streaming is supported for the [Text to Speech API](/docs/api-reference/text-to-speech/stream), [Voice Changer API](/docs/api-reference/speech-to-speech/stream) & [Audio Isolation API](/docs/api-reference/audio-isolation/stream). This section focuses on how streaming works for requests made to the Text to Speech API.

In Python, a streaming request looks like:

```python
from elevenlabs import stream
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs()

audio_stream = elevenlabs.text_to_speech.stream(
    text="This is a test",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2"
)

# option 1: play the streamed audio locally
stream(audio_stream)

# option 2: process the audio bytes manually
for chunk in audio_stream:
    if isinstance(chunk, bytes):
        print(chunk)
```

In Node / Typescript, a streaming request looks like:

```javascript maxLines=0
import { ElevenLabsClient, stream } from '@elevenlabs/elevenlabs-js';
import { Readable } from 'stream';

const elevenlabs = new ElevenLabsClient();

async function main() {
  const audioStream = await elevenlabs.textToSpeech.stream('JBFqnCBsd6RMkjVDRZzb', {
    text: 'This is a test',
    modelId: 'eleven_multilingual_v2',
  });

  // option 1: play the streamed audio locally
  await stream(Readable.from(audioStream));

  // option 2: process the audio manually
  for await (const chunk of audioStream) {
    console.log(chunk);
  }
}

main();
```


# List agent branches

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches

Returns a list of branches an agent has

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/list

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Agent Branches
  version: endpoint_conversationalAi/agents/branches.list
paths:
  /v1/convai/agents/{agent_id}/branches:
    get:
      operationId: list
      summary: List Agent Branches
      description: Returns a list of branches an agent has
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: include_archived
          in: query
          description: Whether archived branches should be included
          required: false
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: How many results at most should be returned
          required: false
          schema:
            type: integer
            default: 100
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ListResponseAgentBranchSummary'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:ListResponseMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        draft_exists:
          type: boolean
          default: false
          description: Whether a draft exists for the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived
    type_:ListResponseAgentBranchSummary:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/type_:ListResponseMeta'
        results:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentBranchSummary'
      required:
        - results

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.list("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        includeArchived: true,
        limit: 1,
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.list(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    include_archived=True,
    limit=1
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches?include_archived=true&limit=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create agent branch

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches
Content-Type: application/json

Create a new branch from a given version of main branch

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create A New Branch
  version: endpoint_conversationalAi/agents/branches.create
paths:
  /v1/convai/agents/{agent_id}/branches:
    post:
      operationId: create
      summary: Create A New Branch
      description: Create a new branch from a given version of main branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:CreateAgentBranchResponseModel'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_version_id:
                  type: string
                  description: ID of the version to branch from
                name:
                  type: string
                  description: Name of the branch. It is unique within the agent.
                description:
                  type: string
                  description: Description for the branch
                conversation_config:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Changes to apply to conversation config
                platform_settings:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Changes to apply to platform settings
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: Updated workflow definition
              required:
                - parent_version_id
                - name
                - description
components:
  schemas:
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstLessThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOrEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstGreaterThanOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstEqualsOperatorNodeInputLeft:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstAndOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowExpressionConditionModelInputExpression:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputForwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInputBackwardCondition:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - expression
              description: 'Discriminator value: expression'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            expression:
              $ref: >-
                #/components/schemas/type_:WorkflowExpressionConditionModelInputExpression
              description: Expression to evaluate.
          required:
            - type
            - expression
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            condition:
              type: string
              description: Condition to evaluate
          required:
            - type
            - condition
        - type: object
          properties:
            type:
              type: string
              enum:
                - result
              description: 'Discriminator value: result'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
            successful:
              type: boolean
              description: >-
                Whether all tools in the previously executed tool node were
                executed successfully.
          required:
            - type
            - successful
        - type: object
          properties:
            type:
              type: string
              enum:
                - unconditional
              description: 'Discriminator value: unconditional'
            label:
              type: string
              description: >-
                Optional human-readable label for the condition used throughout
                the UI.
          required:
            - type
      discriminator:
        propertyName: type
    type_:WorkflowEdgeModelInput:
      type: object
      properties:
        source:
          type: string
          description: ID of the source node.
        target:
          type: string
          description: ID of the target node.
        forward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputForwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            forward direction (source to target).
        backward_condition:
          $ref: '#/components/schemas/type_:WorkflowEdgeModelInputBackwardCondition'
          description: >-
            Condition that must be met for the edge to be traversed in the
            backward direction (target to source).
      required:
        - source
        - target
    type_:PositionInput:
      type: object
      properties:
        x:
          type: number
          format: double
          default: 0
        'y':
          type: number
          format: double
          default: 0
    type_:AsrQuality:
      type: string
      enum:
        - type: stringLiteral
          value: high
    type_:AsrProvider:
      type: string
      enum:
        - value: elevenlabs
        - value: scribe_realtime
    type_:AsrInputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:AsrConversationalConfigWorkflowOverride:
      type: object
      properties:
        quality:
          $ref: '#/components/schemas/type_:AsrQuality'
          description: The quality of the transcription
        provider:
          $ref: '#/components/schemas/type_:AsrProvider'
          description: The provider of the transcription service
        user_input_audio_format:
          $ref: '#/components/schemas/type_:AsrInputFormat'
          description: The format of the audio to be transcribed
        keywords:
          type: array
          items:
            type: string
          description: Keywords to boost prediction probability for
    type_:SoftTimeoutConfigWorkflowOverride:
      type: object
      properties:
        timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before showing the predefined message while waiting
            for LLM response. Set to -1 to disable.
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
        use_llm_generated_message:
          type: boolean
          description: >-
            If enabled, the soft timeout message will be generated dynamically
            instead of using the static message.
    type_:TurnEagerness:
      type: string
      enum:
        - value: patient
        - value: normal
        - value: eager
    type_:SpellingPatience:
      type: string
      enum:
        - value: auto
        - value: 'off'
    type_:TurnConfigWorkflowOverride:
      type: object
      properties:
        turn_timeout:
          type: number
          format: double
          description: Maximum wait time for the user's reply before re-engaging the user
        initial_wait_time:
          type: number
          format: double
          description: >-
            How long the agent will wait for the user to start the conversation
            if the first message is empty. If not set, uses the regular
            turn_timeout.
        silence_end_call_timeout:
          type: number
          format: double
          description: >-
            Maximum wait time since the user last spoke before terminating the
            call
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigWorkflowOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
        turn_eagerness:
          $ref: '#/components/schemas/type_:TurnEagerness'
          description: >-
            Controls how eager the agent is to respond. Low = less eager (waits
            longer), Standard = default eagerness, High = more eager (responds
            sooner)
        spelling_patience:
          $ref: '#/components/schemas/type_:SpellingPatience'
          description: >-
            Controls if the agent should be more patient when user is spelling
            numbers and named entities. Auto = model based, Off = never wait
            extra
        speculative_turn:
          type: boolean
          description: >-
            When enabled, starts generating LLM responses during silence before
            full turn confidence is reached, reducing perceived latency. May
            increase LLM costs.
    type_:TtsConversationalModel:
      type: string
      enum:
        - value: eleven_turbo_v2
        - value: eleven_turbo_v2_5
        - value: eleven_flash_v2
        - value: eleven_flash_v2_5
        - value: eleven_multilingual_v2
        - value: eleven_v3_conversational
    type_:TtsModelFamily:
      type: string
      enum:
        - value: turbo
        - value: flash
        - value: multilingual
        - value: v3_conversational
    type_:TtsOptimizeStreamingLatency:
      type: integer
    type_:SupportedVoice:
      type: object
      properties:
        label:
          type: string
        voice_id:
          type: string
        description:
          type: string
        language:
          type: string
        model_family:
          $ref: '#/components/schemas/type_:TtsModelFamily'
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
        stability:
          type: number
          format: double
        speed:
          type: number
          format: double
        similarity_boost:
          type: number
          format: double
      required:
        - label
        - voice_id
    type_:SuggestedAudioTag:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Audio tag to use (for best performance, 1-2 words, e.g., 'happy',
            'excited')
        description:
          type: string
          description: Optional description of when to use this tag
      required:
        - tag
    type_:TtsOutputFormat:
      type: string
      enum:
        - value: pcm_8000
        - value: pcm_16000
        - value: pcm_22050
        - value: pcm_24000
        - value: pcm_44100
        - value: pcm_48000
        - value: ulaw_8000
    type_:TextNormalisationType:
      type: string
      enum:
        - value: system_prompt
        - value: elevenlabs
    type_:PydanticPronunciationDictionaryVersionLocator:
      type: object
      properties:
        pronunciation_dictionary_id:
          type: string
          description: The ID of the pronunciation dictionary
        version_id:
          type: string
          description: The ID of the version of the pronunciation dictionary
      required:
        - pronunciation_dictionary_id
    type_:TtsConversationalConfigWorkflowOverrideInput:
      type: object
      properties:
        model_id:
          $ref: '#/components/schemas/type_:TtsConversationalModel'
          description: The model to use for TTS
        voice_id:
          type: string
          description: The voice ID to use for TTS
        supported_voices:
          type: array
          items:
            $ref: '#/components/schemas/type_:SupportedVoice'
          description: Additional supported voices for the agent
        suggested_audio_tags:
          type: array
          items:
            $ref: '#/components/schemas/type_:SuggestedAudioTag'
          description: >-
            Suggested audio tags to boost expressive speech (for eleven_v3 and
            eleven_v3_conversational models). The agent can still use other tags
            not listed here.
        agent_output_audio_format:
          $ref: '#/components/schemas/type_:TtsOutputFormat'
          description: The audio format to use for TTS
        optimize_streaming_latency:
          $ref: '#/components/schemas/type_:TtsOptimizeStreamingLatency'
          description: The optimization for streaming latency
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
        text_normalisation_type:
          $ref: '#/components/schemas/type_:TextNormalisationType'
          description: >-
            Method for converting numbers to words before converting text to
            speech. If set to SYSTEM_PROMPT, the system prompt will be updated
            to include normalization instructions. If set to ELEVENLABS, the
            text will be normalized after generation, incurring slight
            additional latency.
        pronunciation_dictionary_locators:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PydanticPronunciationDictionaryVersionLocator
          description: The pronunciation dictionary locators
    type_:ClientEvent:
      type: string
      enum:
        - value: conversation_initiation_metadata
        - value: asr_initiation_metadata
        - value: ping
        - value: audio
        - value: interruption
        - value: user_transcript
        - value: tentative_user_transcript
        - value: agent_response
        - value: agent_response_correction
        - value: client_tool_call
        - value: mcp_tool_call
        - value: mcp_connection_status
        - value: agent_tool_request
        - value: agent_tool_response
        - value: agent_response_metadata
        - value: vad_score
        - value: agent_chat_response_part
        - value: internal_turn_probability
        - value: internal_tentative_agent_response
    type_:ConversationConfigWorkflowOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
        max_duration_seconds:
          type: integer
          description: The maximum duration of a conversation in seconds
        client_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to the client
        monitoring_enabled:
          type: boolean
          description: Enable real-time monitoring of conversations via WebSocket
        monitoring_events:
          type: array
          items:
            $ref: '#/components/schemas/type_:ClientEvent'
          description: The events that will be sent to monitoring connections.
    type_:SoftTimeoutConfigOverride:
      type: object
      properties:
        message:
          type: string
          description: >-
            Message to show when soft timeout is reached while waiting for LLM
            response
    type_:TurnConfigOverride:
      type: object
      properties:
        soft_timeout_config:
          $ref: '#/components/schemas/type_:SoftTimeoutConfigOverride'
          description: >-
            Configuration for soft timeout functionality. Provides immediate
            feedback during longer LLM responses.
    type_:TtsConversationalConfigOverride:
      type: object
      properties:
        voice_id:
          type: string
          description: The voice ID to use for TTS
        stability:
          type: number
          format: double
          description: The stability of generated speech
        speed:
          type: number
          format: double
          description: The speed of generated speech
        similarity_boost:
          type: number
          format: double
          description: The similarity boost for generated speech
    type_:ConversationConfigOverride:
      type: object
      properties:
        text_only:
          type: boolean
          description: >-
            If enabled audio will not be processed and only text will be used,
            use to avoid audio pricing.
    type_:Llm:
      type: string
      enum:
        - value: gpt-4o-mini
        - value: gpt-4o
        - value: gpt-4
        - value: gpt-4-turbo
        - value: gpt-4.1
        - value: gpt-4.1-mini
        - value: gpt-4.1-nano
        - value: gpt-5
        - value: gpt-5.1
        - value: gpt-5.2
        - value: gpt-5.2-chat-latest
        - value: gpt-5-mini
        - value: gpt-5-nano
        - value: gpt-3.5-turbo
        - value: gemini-1.5-pro
        - value: gemini-1.5-flash
        - value: gemini-2.0-flash
        - value: gemini-2.0-flash-lite
        - value: gemini-2.5-flash-lite
        - value: gemini-2.5-flash
        - value: gemini-3-pro-preview
        - value: gemini-3-flash-preview
        - value: claude-sonnet-4-5
        - value: claude-sonnet-4
        - value: claude-haiku-4-5
        - value: claude-3-7-sonnet
        - value: claude-3-5-sonnet
        - value: claude-3-5-sonnet-v1
        - value: claude-3-haiku
        - value: grok-beta
        - value: custom-llm
        - value: qwen3-4b
        - value: qwen3-30b-a3b
        - value: gpt-oss-20b
        - value: gpt-oss-120b
        - value: glm-45-air-fp8
        - value: gemini-2.5-flash-preview-09-2025
        - value: gemini-2.5-flash-lite-preview-09-2025
        - value: gemini-2.5-flash-preview-05-20
        - value: gemini-2.5-flash-preview-04-17
        - value: gemini-2.5-flash-lite-preview-06-17
        - value: gemini-2.0-flash-lite-001
        - value: gemini-2.0-flash-001
        - value: gemini-1.5-flash-002
        - value: gemini-1.5-flash-001
        - value: gemini-1.5-pro-002
        - value: gemini-1.5-pro-001
        - value: claude-sonnet-4@20250514
        - value: claude-sonnet-4-5@20250929
        - value: claude-haiku-4-5@20251001
        - value: claude-3-7-sonnet@20250219
        - value: claude-3-5-sonnet@20240620
        - value: claude-3-5-sonnet-v2@20241022
        - value: claude-3-haiku@20240307
        - value: gpt-5-2025-08-07
        - value: gpt-5.1-2025-11-13
        - value: gpt-5.2-2025-12-11
        - value: gpt-5-mini-2025-08-07
        - value: gpt-5-nano-2025-08-07
        - value: gpt-4.1-2025-04-14
        - value: gpt-4.1-mini-2025-04-14
        - value: gpt-4.1-nano-2025-04-14
        - value: gpt-4o-mini-2024-07-18
        - value: gpt-4o-2024-11-20
        - value: gpt-4o-2024-08-06
        - value: gpt-4o-2024-05-13
        - value: gpt-4-0613
        - value: gpt-4-0314
        - value: gpt-4-turbo-2024-04-09
        - value: gpt-3.5-turbo-0125
        - value: gpt-3.5-turbo-1106
        - value: watt-tool-8b
        - value: watt-tool-70b
    type_:PromptAgentApiModelOverride:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
    type_:AgentConfigOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelOverride'
          description: The prompt for the agent
    type_:ConversationConfigClientOverrideInput:
      type: object
      properties:
        turn:
          $ref: '#/components/schemas/type_:TurnConfigOverride'
          description: Configuration for turn detection
        tts:
          $ref: '#/components/schemas/type_:TtsConversationalConfigOverride'
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigOverride'
          description: Configuration for conversational events
        agent:
          $ref: '#/components/schemas/type_:AgentConfigOverrideInput'
          description: Agent specific configuration
    type_:LanguagePresetTranslation:
      type: object
      properties:
        source_hash:
          type: string
        text:
          type: string
      required:
        - source_hash
        - text
    type_:LanguagePresetInput:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/type_:ConversationConfigClientOverrideInput'
          description: The overrides for the language preset
        first_message_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the first message
        soft_timeout_translation:
          $ref: '#/components/schemas/type_:LanguagePresetTranslation'
          description: The translation of the soft timeout message
      required:
        - overrides
    type_:VadConfigWorkflowOverride:
      type: object
      properties: {}
    type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfigWorkflowOverride:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigWorkflowOverrideDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:LlmReasoningEffort:
      type: string
      enum:
        - value: none
        - value: minimal
        - value: low
        - value: medium
        - value: high
    type_:DynamicVariableAssignment:
      type: object
      properties:
        source:
          type: string
          enum:
            - type: stringLiteral
              value: response
          description: >-
            The source to extract the value from. Currently only 'response' is
            supported.
        dynamic_variable:
          type: string
          description: The name of the dynamic variable to assign the extracted value to
        value_path:
          type: string
          description: >-
            Dot notation path to extract the value from the source (e.g.,
            'user.name' or 'data.0.id')
      required:
        - dynamic_variable
        - value_path
    type_:ToolCallSoundType:
      type: string
      enum:
        - value: typing
        - value: elevator1
        - value: elevator2
        - value: elevator3
        - value: elevator4
    type_:ToolCallSoundBehavior:
      type: string
      enum:
        - value: auto
        - value: always
    type_:AgentTransfer:
      type: object
      properties:
        agent_id:
          type: string
        condition:
          type: string
        delay_ms:
          type: integer
          default: 0
        transfer_message:
          type: string
        enable_transferred_agent_first_message:
          type: boolean
          default: false
      required:
        - agent_id
        - condition
    type_:PhoneNumberTransferCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:PhoneNumberTransferTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:TransferTypeEnum:
      type: string
      enum:
        - value: blind
        - value: conference
        - value: sip_refer
    type_:PhoneNumberTransfer:
      type: object
      properties:
        custom_sip_headers:
          type: array
          items:
            $ref: '#/components/schemas/type_:PhoneNumberTransferCustomSipHeadersItem'
          description: >-
            Custom SIP headers to include when transferring the call. Each
            header can be either a static value or a dynamic variable reference.
        transfer_destination:
          $ref: '#/components/schemas/type_:PhoneNumberTransferTransferDestination'
        phone_number:
          type: string
        condition:
          type: string
        transfer_type:
          $ref: '#/components/schemas/type_:TransferTypeEnum'
      required:
        - condition
    type_:SystemToolConfigInputParams:
      oneOf:
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - end_call
              description: 'Discriminator value: end_call'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - language_detection
              description: 'Discriminator value: language_detection'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - play_keypad_touch_tone
              description: 'Discriminator value: play_keypad_touch_tone'
            use_out_of_band_dtmf:
              type: boolean
              default: false
              description: >-
                If true, send DTMF tones out-of-band using RFC 4733 (useful for
                SIP calls only). If false, send DTMF as in-band audio tones
                (default, works for all call types).
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - skip_turn
              description: 'Discriminator value: skip_turn'
          required:
            - system_tool_type
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_agent
              description: 'Discriminator value: transfer_to_agent'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:AgentTransfer'
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - transfer_to_number
              description: 'Discriminator value: transfer_to_number'
            transfers:
              type: array
              items:
                $ref: '#/components/schemas/type_:PhoneNumberTransfer'
            enable_client_message:
              type: boolean
              default: true
              description: >-
                Whether to play a message to the client while they wait for
                transfer. Defaults to true for backward compatibility.
          required:
            - system_tool_type
            - transfers
        - type: object
          properties:
            system_tool_type:
              type: string
              enum:
                - voicemail_detection
              description: 'Discriminator value: voicemail_detection'
            voicemail_message:
              type: string
              description: >-
                Optional message to leave on voicemail when detected. If not
                provided, the call will end immediately when voicemail is
                detected. Supports dynamic variables (e.g., {{system__time}},
                {{system__call_duration_secs}}, {{custom_variable}}).
          required:
            - system_tool_type
      discriminator:
        propertyName: system_tool_type
    type_:SystemToolConfigInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - &ref_0
              type: stringLiteral
              value: system
          description: The type of tool
        name:
          type: string
        description:
          type: string
          default: ''
          description: >-
            Description of when the tool should be used and what it does. Leave
            empty to use the default description that's optimized for the
            specific tool type.
        response_timeout_secs:
          type: integer
          default: 20
          description: The maximum time in seconds to wait for the tool call to complete.
        disable_interruptions:
          type: boolean
          default: false
          description: >-
            If true, the user will not be able to interrupt the agent while this
            tool is running.
        force_pre_tool_speech:
          type: boolean
          default: false
          description: If true, the agent will speak before the tool call.
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/type_:DynamicVariableAssignment'
          description: >-
            Configuration for extracting values from tool responses and
            assigning them to dynamic variables
        tool_call_sound:
          $ref: '#/components/schemas/type_:ToolCallSoundType'
          description: >-
            Predefined tool call sound type to play during tool execution. If
            not specified, no tool call sound will be played.
        tool_call_sound_behavior:
          $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
          description: >-
            Determines when the tool call sound should play. 'auto' only plays
            when there's pre-tool speech, 'always' plays for every tool call.
        params:
          $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
      required:
        - name
        - params
    type_:BuiltInToolsWorkflowOverrideInput:
      type: object
      properties:
        end_call:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The end call tool
        language_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The language detection tool
        transfer_to_agent:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to agent tool
        transfer_to_number:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The transfer to number tool
        skip_turn:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The skip turn tool
        play_keypad_touch_tone:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The play DTMF tool
        voicemail_detection:
          $ref: '#/components/schemas/type_:SystemToolConfigInput'
          description: The voicemail detection tool
    type_:KnowledgeBaseDocumentType:
      type: string
      enum:
        - value: file
        - value: url
        - value: text
        - value: folder
    type_:DocumentUsageModeEnum:
      type: string
      enum:
        - value: prompt
        - value: auto
    type_:KnowledgeBaseLocator:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:KnowledgeBaseDocumentType'
          description: The type of the knowledge base
        name:
          type: string
          description: The name of the knowledge base
        id:
          type: string
          description: The ID of the knowledge base
        usage_mode:
          $ref: '#/components/schemas/type_:DocumentUsageModeEnum'
          description: The usage mode of the knowledge base
      required:
        - type
        - name
        - id
    type_:ConvAiSecretLocator:
      type: object
      properties:
        secret_id:
          type: string
      required:
        - secret_id
    type_:ConvAiDynamicVariable:
      type: object
      properties:
        variable_name:
          type: string
      required:
        - variable_name
    type_:CustomLlmRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:CustomLlmapiType:
      type: string
      enum:
        - value: chat_completions
        - value: responses
    type_:CustomLlm:
      type: object
      properties:
        url:
          type: string
          description: The URL of the Chat Completions compatible endpoint
        model_id:
          type: string
          description: The model ID to be used if URL serves multiple models
        api_key:
          $ref: '#/components/schemas/type_:ConvAiSecretLocator'
          description: The API key for authentication
        request_headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:CustomLlmRequestHeadersValue'
          description: Headers that should be included in the request
        api_version:
          type: string
          description: The API version to use for the request
        api_type:
          $ref: '#/components/schemas/type_:CustomLlmapiType'
          description: The API type to use (chat_completions or responses)
      required:
        - url
    type_:EmbeddingModelEnum:
      type: string
      enum:
        - value: e5_mistral_7b_instruct
        - value: multilingual_e5_large_instruct
    type_:RagConfigWorkflowOverride:
      type: object
      properties:
        enabled:
          type: boolean
        embedding_model:
          $ref: '#/components/schemas/type_:EmbeddingModelEnum'
        max_vector_distance:
          type: number
          format: double
          description: Maximum vector distance of retrieved chunks.
        max_documents_length:
          type: integer
          description: Maximum total length of document chunks retrieved from RAG.
        max_retrieved_rag_chunks_count:
          type: integer
          description: >-
            Maximum number of RAG document chunks to initially retrieve from the
            vector store. These are then further filtered by vector distance and
            total length.
        query_rewrite_prompt_override:
          type: string
          description: >-
            Custom prompt for rewriting user queries before RAG retrieval. The
            conversation history will be automatically appended at the end. If
            not set, the default prompt will be used.
    type_:BackupLlmDefault:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: default
    type_:BackupLlmDisabled:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: disabled
    type_:BackupLlmOverride:
      type: object
      properties:
        preference:
          type: string
          enum:
            - type: stringLiteral
              value: override
        order:
          type: array
          items:
            $ref: '#/components/schemas/type_:Llm'
      required:
        - order
    type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig:
      oneOf:
        - $ref: '#/components/schemas/type_:BackupLlmDefault'
        - $ref: '#/components/schemas/type_:BackupLlmDisabled'
        - $ref: '#/components/schemas/type_:BackupLlmOverride'
    type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: integer
        - type: boolean
    type_:DynamicVariablesConfig:
      type: object
      properties:
        dynamic_variable_placeholders:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:DynamicVariablesConfigDynamicVariablePlaceholdersValue
          description: A dictionary of dynamic variable placeholders and their values
    type_:ToolExecutionMode:
      type: string
      enum:
        - value: immediate
        - value: post_tool_speech
        - value: async
    type_:LiteralOverrideConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralOverride:
      type: object
      properties:
        description:
          type: string
        dynamic_variable:
          type: string
        constant_value:
          $ref: '#/components/schemas/type_:LiteralOverrideConstantValue'
    type_:QueryOverride:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        required:
          type: array
          items:
            type: string
    type_:ObjectOverrideInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralOverride'
        - $ref: '#/components/schemas/type_:ObjectOverrideInput'
    type_:ObjectOverrideInput:
      type: object
      properties:
        description:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:ObjectOverrideInputPropertiesValue'
        required:
          type: array
          items:
            type: string
    type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:ResponseFilterMode:
      type: string
      enum:
        - value: all
        - value: allow
    type_:ApiIntegrationWebhookOverridesInput:
      type: object
      properties:
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralOverride'
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryOverride'
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectOverrideInput'
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ApiIntegrationWebhookOverridesInputRequestHeadersValue
        response_filter_mode:
          $ref: '#/components/schemas/type_:ResponseFilterMode'
        response_filters:
          type: array
          items:
            type: string
    type_:LiteralJsonSchemaPropertyType:
      type: string
      enum:
        - value: boolean
        - value: string
        - value: integer
        - value: number
    type_:LiteralJsonSchemaPropertyConstantValue:
      oneOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
    type_:LiteralJsonSchemaProperty:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyType'
        description:
          type: string
          default: ''
          description: >-
            The description of the property. When set, the LLM will provide the
            value based on this description. Mutually exclusive with
            dynamic_variable, is_system_provided, and constant_value.
        enum:
          type: array
          items:
            type: string
          description: List of allowed string values for string type parameters
        is_system_provided:
          type: boolean
          default: false
          description: >-
            If true, the value will be populated by the system at runtime. Used
            by API Integration Webhook tools for templating. Mutually exclusive
            with description, dynamic_variable, and constant_value.
        dynamic_variable:
          type: string
          default: ''
          description: >-
            The name of the dynamic variable to use for this property's value.
            Mutually exclusive with description, is_system_provided, and
            constant_value.
        constant_value:
          $ref: '#/components/schemas/type_:LiteralJsonSchemaPropertyConstantValue'
          description: >-
            A constant value to use for this property. Mutually exclusive with
            description, dynamic_variable, and is_system_provided.
      required:
        - type
    type_:ArrayJsonSchemaPropertyInputItems:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ArrayJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: array
        description:
          type: string
          default: ''
        items:
          $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInputItems'
      required:
        - items
    type_:ObjectJsonSchemaPropertyInputPropertiesValue:
      oneOf:
        - $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        - $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
        - $ref: '#/components/schemas/type_:ArrayJsonSchemaPropertyInput'
    type_:ObjectJsonSchemaPropertyInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: object
        required:
          type: array
          items:
            type: string
        description:
          type: string
          default: ''
        properties:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:ObjectJsonSchemaPropertyInputPropertiesValue
    type_:WebhookToolApiSchemaConfigInputRequestHeadersValue:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/type_:ConvAiSecretLocator'
        - $ref: '#/components/schemas/type_:ConvAiDynamicVariable'
    type_:WebhookToolApiSchemaConfigInputMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PUT
        - value: PATCH
        - value: DELETE
      default: GET
    type_:QueryParamsJsonSchema:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
        required:
          type: array
          items:
            type: string
      required:
        - properties
    type_:WebhookToolApiSchemaConfigInputContentType:
      type: string
      enum:
        - value: application/json
        - value: application/x-www-form-urlencoded
      default: application/json
    type_:AuthConnectionLocator:
      type: object
      properties:
        auth_connection_id:
          type: string
      required:
        - auth_connection_id
    type_:WebhookToolApiSchemaConfigInput:
      type: object
      properties:
        request_headers:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/type_:WebhookToolApiSchemaConfigInputRequestHeadersValue
          description: Headers that should be included in the request
        url:
          type: string
          description: >-
            The URL that the webhook will be sent to. May include path
            parameters, e.g. https://example.com/agents/{agent_id}
        method:
          $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInputMethod'
          description: The HTTP method to use for the webhook
        path_params_schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LiteralJsonSchemaProperty'
          description: >-
            Schema for path parameters, if any. The keys should match the
            placeholders in the URL.
        query_params_schema:
          $ref: '#/components/schemas/type_:QueryParamsJsonSchema'
          description: >-
            Schema for any query params, if any. These will be added to end of
            the URL as query params. Note: properties in a query param must all
            be literal types
        request_body_schema:
          $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
          description: >-
            Schema for the body parameters, if any. Used for POST/PATCH/PUT
            requests. The schema should be an object which will be sent as the
            json body
        content_type:
          $ref: >-
            #/components/schemas/type_:WebhookToolApiSchemaConfigInputContentType
          description: >-
            Content type for the request body. Only applies to POST/PUT/PATCH
            requests.
        auth_connection:
          $ref: '#/components/schemas/type_:AuthConnectionLocator'
          description: Optional auth connection to use for authentication with this webhook
      required:
        - url
    type_:PromptAgentApiModelWorkflowOverrideInputToolsItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - api_integration_webhook
              description: 'Discriminator value: api_integration_webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            tool_version:
              type: string
              default: 1.0.0
              description: The version of the API integration tool
            api_integration_id:
              type: string
            api_integration_connection_id:
              type: string
            api_schema_overrides:
              $ref: '#/components/schemas/type_:ApiIntegrationWebhookOverridesInput'
              description: User overrides applied on top of the base api_schema
          required:
            - type
            - name
            - description
            - api_integration_id
            - api_integration_connection_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - client
              description: 'Discriminator value: client'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 1 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            parameters:
              $ref: '#/components/schemas/type_:ObjectJsonSchemaPropertyInput'
              description: Schema for any parameters to pass to the client
            expects_response:
              type: boolean
              default: false
              description: >-
                If true, calling this tool should block the conversation until
                the client responds with some response which is passed to the
                llm. If false then we will continue the conversation without
                waiting for the client to respond, this is useful to show
                content to a user but not block the conversation
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
          required:
            - type
            - name
            - description
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp
              description: 'Discriminator value: mcp'
            value:
              description: Any type
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - *ref_0
              description: The type of tool
            name:
              type: string
            description:
              type: string
              default: ''
              description: >-
                Description of when the tool should be used and what it does.
                Leave empty to use the default description that's optimized for
                the specific tool type.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete.
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            params:
              $ref: '#/components/schemas/type_:SystemToolConfigInputParams'
          required:
            - type
            - name
            - params
        - type: object
          properties:
            type:
              type: string
              enum:
                - webhook
              description: 'Discriminator value: webhook'
            name:
              type: string
            description:
              type: string
              description: Description of when the tool should be used and what it does.
            response_timeout_secs:
              type: integer
              default: 20
              description: >-
                The maximum time in seconds to wait for the tool call to
                complete. Must be between 5 and 120 seconds (inclusive).
            disable_interruptions:
              type: boolean
              default: false
              description: >-
                If true, the user will not be able to interrupt the agent while
                this tool is running.
            force_pre_tool_speech:
              type: boolean
              default: false
              description: If true, the agent will speak before the tool call.
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/type_:DynamicVariableAssignment'
              description: >-
                Configuration for extracting values from tool responses and
                assigning them to dynamic variables
            tool_call_sound:
              $ref: '#/components/schemas/type_:ToolCallSoundType'
              description: >-
                Predefined tool call sound type to play during tool execution.
                If not specified, no tool call sound will be played.
            tool_call_sound_behavior:
              $ref: '#/components/schemas/type_:ToolCallSoundBehavior'
              description: >-
                Determines when the tool call sound should play. 'auto' only
                plays when there's pre-tool speech, 'always' plays for every
                tool call.
            dynamic_variables:
              $ref: '#/components/schemas/type_:DynamicVariablesConfig'
              description: Configuration for dynamic variables
            execution_mode:
              $ref: '#/components/schemas/type_:ToolExecutionMode'
              description: >-
                Determines when and how the tool executes: 'immediate' executes
                the tool right away when requested by the LLM,
                'post_tool_speech' waits for the agent to finish speaking before
                executing, 'async' runs the tool in the background without
                blocking - best for long-running operations.
            api_schema:
              $ref: '#/components/schemas/type_:WebhookToolApiSchemaConfigInput'
              description: >-
                The schema for the outgoing webhoook, including parameters and
                URL specification
          required:
            - type
            - name
            - description
            - api_schema
      discriminator:
        propertyName: type
    type_:PromptAgentApiModelWorkflowOverrideInput:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt for the agent
        llm:
          $ref: '#/components/schemas/type_:Llm'
          description: >-
            The LLM to query with the prompt and the chat history. If using data
            residency, the LLM must be supported in the data residency
            environment
        reasoning_effort:
          $ref: '#/components/schemas/type_:LlmReasoningEffort'
          description: Reasoning effort of the model. Only available for some models.
        thinking_budget:
          type: integer
          description: >-
            Max number of tokens used for thinking. Use 0 to turn off if
            supported by the model.
        temperature:
          type: number
          format: double
          description: The temperature for the LLM
        max_tokens:
          type: integer
          description: If greater than 0, maximum number of tokens the LLM can predict
        tool_ids:
          type: array
          items:
            type: string
          description: A list of IDs of tools used by the agent
        built_in_tools:
          $ref: '#/components/schemas/type_:BuiltInToolsWorkflowOverrideInput'
          description: Built-in system tools to be used by the agent
        mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of MCP server ids to be used by the agent
        native_mcp_server_ids:
          type: array
          items:
            type: string
          description: A list of Native MCP server ids to be used by the agent
        knowledge_base:
          type: array
          items:
            $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
          description: A list of knowledge bases to be used by the agent
        custom_llm:
          $ref: '#/components/schemas/type_:CustomLlm'
          description: Definition for a custom LLM if LLM field is set to 'CUSTOM_LLM'
        ignore_default_personality:
          type: boolean
          description: >-
            Whether to remove the default personality lines from the system
            prompt
        rag:
          $ref: '#/components/schemas/type_:RagConfigWorkflowOverride'
          description: Configuration for RAG
        timezone:
          type: string
          description: >-
            Timezone for displaying current time in system prompt. If set, the
            current time will be included in the system prompt using this
            timezone. Must be a valid timezone name (e.g., 'America/New_York',
            'Europe/London', 'UTC').
        backup_llm_config:
          $ref: >-
            #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig
          description: >-
            Configuration for backup LLM cascading. Can be disabled, use system
            defaults, or specify custom order.
        cascade_timeout_seconds:
          type: number
          format: double
          description: >-
            Time in seconds before cascading to backup LLM. Must be between 2
            and 15 seconds.
        tools:
          type: array
          items:
            $ref: >-
              #/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInputToolsItem
          description: >-
            A list of tools that the agent can use over the course of the
            conversation, use tool_ids instead
    type_:AgentConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        first_message:
          type: string
          description: >-
            If non-empty, the first message the agent will say. If empty, the
            agent waits for the user to start the discussion.
        language:
          type: string
          description: Language of the agent - used for ASR and TTS
        hinglish_mode:
          type: boolean
          description: >-
            When enabled and language is Hindi, the agent will respond in
            Hinglish
        dynamic_variables:
          $ref: '#/components/schemas/type_:DynamicVariablesConfigWorkflowOverride'
          description: Configuration for dynamic variables
        disable_first_message_interruptions:
          type: boolean
          description: >-
            If true, the user will not be able to interrupt the agent while the
            first message is being delivered.
        prompt:
          $ref: '#/components/schemas/type_:PromptAgentApiModelWorkflowOverrideInput'
          description: The prompt for the agent
    type_:ConversationalConfigApiModelWorkflowOverrideInput:
      type: object
      properties:
        asr:
          $ref: '#/components/schemas/type_:AsrConversationalConfigWorkflowOverride'
          description: Configuration for conversational transcription
        turn:
          $ref: '#/components/schemas/type_:TurnConfigWorkflowOverride'
          description: Configuration for turn detection
        tts:
          $ref: >-
            #/components/schemas/type_:TtsConversationalConfigWorkflowOverrideInput
          description: Configuration for conversational text to speech
        conversation:
          $ref: '#/components/schemas/type_:ConversationConfigWorkflowOverride'
          description: Configuration for conversational events
        language_presets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:LanguagePresetInput'
          description: Language presets for conversations
        vad:
          $ref: '#/components/schemas/type_:VadConfigWorkflowOverride'
          description: Configuration for voice activity detection
        agent:
          $ref: '#/components/schemas/type_:AgentConfigApiModelWorkflowOverrideInput'
          description: Agent specific configuration
    type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic
              description: 'Discriminator value: dynamic'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The dynamic variable name to resolve
          required:
            - type
            - key
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - static
              description: 'Discriminator value: static'
            key:
              type: string
              description: The SIP header name (e.g., 'X-Customer-ID')
            value:
              type: string
              description: The header value
          required:
            - type
            - key
            - value
      discriminator:
        propertyName: type
    type_:WorkflowPhoneNumberNodeModelInputTransferDestination:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone
              description: 'Discriminator value: phone'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_dynamic_variable
              description: 'Discriminator value: phone_dynamic_variable'
            phone_number:
              type: string
          required:
            - type
            - phone_number
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri
              description: 'Discriminator value: sip_uri'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
        - type: object
          properties:
            type:
              type: string
              enum:
                - sip_uri_dynamic_variable
              description: 'Discriminator value: sip_uri_dynamic_variable'
            sip_uri:
              type: string
          required:
            - type
            - sip_uri
      discriminator:
        propertyName: type
    type_:WorkflowToolLocator:
      type: object
      properties:
        tool_id:
          type: string
      required:
        - tool_id
    type_:AgentWorkflowRequestModelNodesValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
              description: 'Discriminator value: end'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - override_agent
              description: 'Discriminator value: override_agent'
            conversation_config:
              $ref: >-
                #/components/schemas/type_:ConversationalConfigApiModelWorkflowOverrideInput
              description: >-
                Configuration overrides applied while the subagent is conducting
                the conversation.
            additional_prompt:
              type: string
              description: >-
                Specific goal for this subagent. It will be added to the system
                prompt and can be used to further refine the agent's behavior in
                this specific context.
            additional_knowledge_base:
              type: array
              items:
                $ref: '#/components/schemas/type_:KnowledgeBaseLocator'
              description: >-
                Additional knowledge base documents that the subagent has access
                to. These will be used in addition to the main agent's
                documents.
            additional_tool_ids:
              type: array
              items:
                type: string
              description: >-
                IDs of additional tools that the subagent has access to. These
                will be used in addition to the main agent's tools.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            label:
              type: string
              description: Human-readable label for the node used throughout the UI.
          required:
            - type
            - label
        - type: object
          properties:
            type:
              type: string
              enum:
                - phone_number
              description: 'Discriminator value: phone_number'
            custom_sip_headers:
              type: array
              items:
                $ref: >-
                  #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem
              description: >-
                Custom SIP headers to include when transferring the call. Each
                header can be either a static value or a dynamic variable
                reference.
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            transfer_destination:
              $ref: >-
                #/components/schemas/type_:WorkflowPhoneNumberNodeModelInputTransferDestination
            transfer_type:
              $ref: '#/components/schemas/type_:TransferTypeEnum'
          required:
            - type
            - transfer_destination
        - type: object
          properties:
            type:
              type: string
              enum:
                - standalone_agent
              description: 'Discriminator value: standalone_agent'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            agent_id:
              type: string
              description: The ID of the agent to transfer the conversation to.
            delay_ms:
              type: integer
              default: 0
              description: >-
                Artificial delay in milliseconds applied before transferring the
                conversation.
            transfer_message:
              type: string
              description: >-
                Optional message sent to the user before the transfer is
                initiated.
            enable_transferred_agent_first_message:
              type: boolean
              default: false
              description: >-
                Whether to enable the transferred agent to send its configured
                first message after the transfer.
          required:
            - type
            - agent_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
              description: 'Discriminator value: start'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
          required:
            - type
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
              description: 'Discriminator value: tool'
            position:
              $ref: '#/components/schemas/type_:PositionInput'
              description: Position of the node in the workflow.
            edge_order:
              type: array
              items:
                type: string
              description: The ids of outgoing edges in the order they should be evaluated.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/type_:WorkflowToolLocator'
              description: >-
                List of tools to execute in parallel. The entire node is
                considered successful if all tools are executed successfully.
          required:
            - type
      discriminator:
        propertyName: type
    type_:AgentWorkflowRequestModel:
      type: object
      properties:
        edges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:WorkflowEdgeModelInput'
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_:AgentWorkflowRequestModelNodesValue'
        prevent_subagent_loops:
          type: boolean
          default: false
          description: Whether to prevent loops in the workflow execution.
    type_:CreateAgentBranchResponseModel:
      type: object
      properties:
        created_branch_id:
          type: string
          description: ID of the created branch
        created_version_id:
          type: string
          description: ID of the first version on the created branch
      required:
        - created_branch_id
        - created_version_id

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        parentVersionId: "parent_version_id",
        name: "name",
        description: "description",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    parent_version_id="parent_version_id",
    name="name",
    description="description"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches"

	payload := strings.NewReader("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches', [
  'body' => '{
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Get agent branch

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}

Get information about a single agent branch

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/get

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Agent Branch
  version: endpoint_conversationalAi/agents/branches.get
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    get:
      operationId: get
      summary: Get Agent Branch
      description: Get information about a single agent branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          description: Unique identifier for the branch.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentBranchResponse'
        '422':
          description: Validation Error
          content: {}
components:
  schemas:
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchBasicInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    type_:AgentVersionParents:
      type: object
      properties:
        in_branch_parent_id:
          type: string
        out_of_branch_parent_id:
          type: string
        merged_into_branch_id:
          type: string
        merged_from_branch_id:
          type: string
    type_:AgentVersionMetadata:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        version_description:
          type: string
        seq_no_in_branch:
          type: integer
        time_committed_secs:
          type: integer
        parents:
          $ref: '#/components/schemas/type_:AgentVersionParents'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
      required:
        - id
        - agent_id
        - branch_id
        - version_description
        - seq_no_in_branch
        - time_committed_secs
        - parents
    type_:AgentBranchResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        parent_branch:
          $ref: '#/components/schemas/type_:AgentBranchBasicInfo'
          description: Parent branch of the branch
        most_recent_versions:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentVersionMetadata'
          description: Most recent versions on the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Update agent branch

PATCH https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}
Content-Type: application/json

Update agent branch properties such as archiving status and protection level

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/update

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Agent Branch
  version: endpoint_conversationalAi/agents/branches.update
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    patch:
      operationId: update
      summary: Update Agent Branch
      description: >-
        Update agent branch properties such as archiving status and protection
        level
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          description: Unique identifier for the branch.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentBranchResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New name for the branch. Must be unique within the agent.
                is_archived:
                  type: boolean
                  description: Whether the branch should be archived
                protection_status:
                  $ref: '#/components/schemas/type_:BranchProtectionStatus'
                  description: The protection level for the branch
components:
  schemas:
    type_:BranchProtectionStatus:
      type: string
      enum:
        - value: writer_perms_required
        - value: admin_perms_required
    type_:ResourceAccessInfoRole:
      type: string
      enum:
        - value: admin
        - value: editor
        - value: commenter
        - value: viewer
    type_:ResourceAccessInfo:
      type: object
      properties:
        is_creator:
          type: boolean
          description: Whether the user making the request is the creator of the agent
        creator_name:
          type: string
          description: Name of the agent's creator
        creator_email:
          type: string
          description: Email of the agent's creator
        role:
          $ref: '#/components/schemas/type_:ResourceAccessInfoRole'
          description: The role of the user making the request
      required:
        - is_creator
        - creator_name
        - creator_email
        - role
    type_:AgentBranchBasicInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    type_:AgentVersionParents:
      type: object
      properties:
        in_branch_parent_id:
          type: string
        out_of_branch_parent_id:
          type: string
        merged_into_branch_id:
          type: string
        merged_from_branch_id:
          type: string
    type_:AgentVersionMetadata:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        branch_id:
          type: string
        version_description:
          type: string
        seq_no_in_branch:
          type: integer
        time_committed_secs:
          type: integer
        parents:
          $ref: '#/components/schemas/type_:AgentVersionParents'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
      required:
        - id
        - agent_id
        - branch_id
        - version_description
        - seq_no_in_branch
        - time_committed_secs
        - parents
    type_:AgentBranchResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        agent_id:
          type: string
        description:
          type: string
        created_at:
          type: integer
        last_committed_at:
          type: integer
        is_archived:
          type: boolean
        protection_status:
          $ref: '#/components/schemas/type_:BranchProtectionStatus'
        access_info:
          $ref: '#/components/schemas/type_:ResourceAccessInfo'
          description: Access information for the branch
        current_live_percentage:
          type: number
          format: double
          default: 0
          description: Percentage of traffic live on the branch
        parent_branch:
          $ref: '#/components/schemas/type_:AgentBranchBasicInfo'
          description: Parent branch of the branch
        most_recent_versions:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentVersionMetadata'
          description: Most recent versions on the branch
      required:
        - id
        - name
        - agent_id
        - description
        - created_at
        - last_committed_at
        - is_archived

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.update("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", {});
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.update(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Delete agent branch

DELETE https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{branch_id}

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/delete

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete V 1 Convai Agents Agent Id Branches Branch Id
  version: endpoint_.deleteV1ConvaiAgentsAgentIdBranchesBranchId
paths:
  /v1/convai/agents/{agent_id}/branches/{branch_id}:
    delete:
      operationId: delete-v-1-convai-agents-agent-id-branches-branch-id
      summary: Delete V 1 Convai Agents Agent Id Branches Branch Id
      tags:
        - []
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: branch_id
          in: path
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.deleteV1ConvaiAgentsAgentIdBranchesBranchId("agent_id", "branch_id");
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.delete_v_1_convai_agents_agent_id_branches_branch_id(
    agent_id="agent_id",
    branch_id="branch_id"
)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_id/branches/branch_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Merge agent branch

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge
Content-Type: application/json

Merge a branch into a target branch

Reference: https://elevenlabs.io/docs/api-reference/agents/branches/merge

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Merge A Branch Into A Target Branch
  version: endpoint_conversationalAi/agents/branches.merge
paths:
  /v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge:
    post:
      operationId: merge
      summary: Merge A Branch Into A Target Branch
      description: Merge a branch into a target branch
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/branches
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: source_branch_id
          in: path
          description: Unique identifier for the source branch to merge from.
          required: true
          schema:
            type: string
        - name: target_branch_id
          in: query
          description: The ID of the target branch to merge into (must be the main branch).
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                archive_source_branch:
                  type: boolean
                  default: true
                  description: Whether to archive the source branch after merging

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.branches.merge("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbrch_8901k4t9z5defmb8vh3e9361y7nj", {
        targetBranchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.branches.merge(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    source_branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
    target_branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches/agtbrch_8901k4t9z5defmb8vh3e9361y7nj/merge?target_branch_id=agtbrch_8901k4t9z5defmb8vh3e9361y7nj")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create deployment

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/deployments
Content-Type: application/json

Create a new deployment for an agent

Reference: https://elevenlabs.io/docs/api-reference/agents/deployments/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Or Update Deployments
  version: endpoint_conversationalAi/agents/deployments.create
paths:
  /v1/convai/agents/{agent_id}/deployments:
    post:
      operationId: create
      summary: Create Or Update Deployments
      description: Create a new deployment for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/deployments
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:AgentDeploymentResponse'
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                deployment_request:
                  $ref: '#/components/schemas/type_:AgentDeploymentRequest'
                  description: Request to create a new deployment
              required:
                - deployment_request
components:
  schemas:
    type_:AgentDeploymentPercentageStrategy:
      type: object
      properties:
        type:
          type: string
          enum:
            - type: stringLiteral
              value: percentage
        traffic_percentage:
          type: number
          format: double
          description: Traffic percentage to deploy
      required:
        - traffic_percentage
    type_:AgentDeploymentRequestItem:
      type: object
      properties:
        branch_id:
          type: string
          description: ID of the branch to deploy
        deployment_strategy:
          $ref: '#/components/schemas/type_:AgentDeploymentPercentageStrategy'
      required:
        - branch_id
        - deployment_strategy
    type_:AgentDeploymentRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/type_:AgentDeploymentRequestItem'
          description: List of deployment requests
      required:
        - requests
    type_:AgentDeploymentResponse:
      type: object
      properties:
        traffic_percentage_branch_id_map:
          type: object
          additionalProperties:
            type: number
            format: double
          description: Map of branch IDs to traffic percentages

```

## SDK Code Examples

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

async function main() {
    const client = new ElevenLabsClient({
        environment: "https://api.elevenlabs.io",
    });
    await client.conversationalAi.agents.deployments.create("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
        deploymentRequest: {
            requests: [
                {
                    branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
                    deploymentStrategy: {
                        trafficPercentage: 0.5,
                        type: "percentage",
                    },
                },
            ],
        },
    });
}
main();

```

```python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.elevenlabs.io"
)

client.conversational_ai.agents.deployments.create(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    deployment_request={
        "requests": [
            {
                "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
                "deployment_strategy": {
                    "traffic_percentage": 0.5,
                    "type": "percentage"
                }
            }
        ]
    }
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments"

	payload := strings.NewReader("{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")
  .header("Content-Type", "application/json")
  .body("{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments', [
  'body' => '{
  "deployment_request": {
    "requests": [
      {
        "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
        "deployment_strategy": {
          "traffic_percentage": 0.5,
          "type": "percentage"
        }
      }
    ]
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"deployment_request\": {\n    \"requests\": [\n      {\n        \"branch_id\": \"agtbrch_8901k4t9z5defmb8vh3e9361y7nj\",\n        \"deployment_strategy\": {\n          \"traffic_percentage\": 0.5,\n          \"type\": \"percentage\"\n        }\n      }\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["deployment_request": ["requests": [
      [
        "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
        "deployment_strategy": [
          "traffic_percentage": 0.5,
          "type": "percentage"
        ]
      ]
    ]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/deployments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

# Create draft

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/drafts
Content-Type: application/json

Create a new draft for an agent

Reference: https://elevenlabs.io/docs/api-reference/agents/drafts/create

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Agent Draft
  version: endpoint_conversationalAi/agents/drafts.create
paths:
  /v1/convai/agents/{agent_id}/drafts:
    post:
      operationId: create
      summary: Create Agent Draft
      description: Create a new draft for an agent
      tags:
        - - subpackage_conversationalAi
          - subpackage_conversationalAi/agents
          - subpackage_conversationalAi/agents/drafts
      parameters:
        - name: agent_id
          in: path
          description: The id of an agent. This is returned on agent creation.
          required: true
          schema:
            type: string
        - name: branch_id
          in: query
          description: The ID of the agent branch to use
          required: true
          schema:
            type: string
        - name: xi-api-key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_config:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Conversation config for the draft
                platform_settings:
                  type: object
                  additionalProperties:
                    description: Any type
                  description: Platform settings for the draft
                workflow:
                  $ref: '#/components/schemas/type_:AgentWorkflowRequestModel'
                  description: Workflow for the draft
                name:
                  type: string
                  description: Name for the draft
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags to help classify and filter the agent
              required:
                - conversation_config
                - platform_settings
                - workflow
                - name
components:
  schemas:
    type_:AstOrOperatorNodeInputChildrenItem:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - neq_operator
              description: 'Discriminator value: neq_operator'
            left:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstNotEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - number_literal
              description: 'Discriminator value: number_literal'
            value:
              type: number
              format: double
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - or_operator
              description: 'Discriminator value: or_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstOrOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - string_literal
              description: 'Discriminator value: string_literal'
            value:
              type: string
              description: Value of this literal.
          required:
            - type
            - value
      discriminator:
        propertyName: type
    type_:AstNotEqualsOperatorNodeInputRight:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - and_operator
              description: 'Discriminator value: and_operator'
            children:
              type: array
              items:
                $ref: '#/components/schemas/type_:AstAndOperatorNodeInputChildrenItem'
              description: Child nodes of the logical operator.
          required:
            - type
            - children
        - type: object
          properties:
            type:
              type: string
              enum:
                - boolean_literal
              description: 'Discriminator value: boolean_literal'
            value:
              type: boolean
              description: Value of this literal.
          required:
            - type
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - dynamic_variable
              description: 'Discriminator value: dynamic_variable'
            name:
              type: string
              description: The name of the dynamic variable.
          required:
            - type
            - name
        - type: object
          properties:
            type:
              type: string
              enum:
                - eq_operator
              description: 'Discriminator value: eq_operator'
            left:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstEqualsOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gt_operator
              description: 'Discriminator value: gt_operator'
            left:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstGreaterThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - gte_operator
              description: 'Discriminator value: gte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/components/schemas/type_:AstGreaterThanOrEqualsOperatorNodeInputRight
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - llm
              description: 'Discriminator value: llm'
            prompt:
              type: string
              description: The prompt to evaluate to a boolean value.
          required:
            - type
            - prompt
        - type: object
          properties:
            type:
              type: string
              enum:
                - lt_operator
              description: 'Discriminator value: lt_operator'
            left:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputLeft'
              description: Left operand of the binary operator.
            right:
              $ref: '#/components/schemas/type_:AstLessThanOperatorNodeInputRight'
              description: Right operand of the binary operator.
          required:
            - type
            - left
            - right
        - type: object
          properties:
            type:
              type: string
              enum:
                - lte_operator
              description: 'Discriminator value: lte_operator'
            left:
              $ref: >-
                #/components/schemas/type_:AstLessThanOrEqualsOperatorNodeInputLeft
              description: Left operand of the binary operator.
            right:
              $ref: >-
                #/compo