# ElevenLabs (/docs/workflows/integrations/elevenlabs)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

The ElevenLabs integration stores your ElevenLabs API key. Voice agents that speak with an
ElevenLabs voice use it to list your voices and pronunciation dictionaries, and to synthesize
speech on each call. The voice settings are under
[ElevenLabs voice character](/docs/agents/voice-agents/voice-and-speech#elevenlabs-voice-character).

There are no ElevenLabs workflow nodes.

## Setup

### 1. Create a restricted API key

In ElevenLabs, create an API key and turn on **Restrict Key**. Grant these permissions and leave
every other one at No Access:

| Permission                       | API scope                         | Needed for                                                                                            |
| -------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| ElevenAgents: Read               | `convai_read`                     | Connecting the key and **Test Connection**. Required.                                                 |
| Voices: Read                     | `voices_read`                     | Listing your ElevenLabs voices in a voice agent's voice picker.                                       |
| Text to Speech: Access           | `text_to_speech`                  | Voice agents speaking with an ElevenLabs voice. Required, and checked by **Test Connection**.         |
| Pronunciation Dictionaries: Read | `pronunciation_dictionaries_read` | Listing pronunciation dictionaries on a voice agent, and fetching each one's latest version per call. |

### 2. Connect it in Tandem

On the **Integrations** page, add an ElevenLabs integration and paste the key. Tandem checks the
key with ElevenLabs before saving it, including a one-character speech synthesis to confirm the
Text to Speech permission.

## Troubleshooting

| What you see                                                                               | What it means                                                                                                                                              |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `The API key you used is missing the permission convai_read to execute this operation.`    | The key is restricted and lacks the named permission. Grant it to the key in ElevenLabs.                                                                   |
| `The API key you used is missing the permission text_to_speech to execute this operation.` | The key can't synthesize speech. Grant it Text to Speech: Access in ElevenLabs.                                                                            |
| A voice agent set to an ElevenLabs voice speaks in an Amazon Polly voice                   | ElevenLabs refused speech during the call, so the agent switched to its Polly standby voice for the rest of that call. Run **Test Connection** to see why. |
| `Invalid API key — check that it hasn't been revoked`                                      | ElevenLabs doesn't recognize the key. It was mistyped, has expired, or was deleted.                                                                        |

To add a permission, edit the key in ElevenLabs. The key itself does not change, so there is
nothing to update in Tandem. Run **Test Connection** again to check it.