> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bolna + Cartesia > Create a Bolna voice AI phone agent that speaks with a Cartesia Sonic voice > [!TIP] > > Last verified: 2026-10-30 ## Overview [Bolna](https://www.bolna.ai/docs/introduction) runs voice AI agents over the phone, chaining a speech-to-text (STT) transcriber, an LLM, and a text-to-speech (TTS) synthesizer on each call. Set [Sonic](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest.md) as the agent's synthesizer to speak every reply with a Cartesia voice. ## Prerequisites * A Bolna account at [platform.bolna.ai](https://platform.bolna.ai) with wallet credits, since calls consume credits * A Bolna API key (`BOLNA_API_KEY`) from [Generate an API key](https://www.bolna.ai/docs/api-reference/introduction) * A phone number to call, in [E.164](https://en.wikipedia.org/wiki/E.164) format (for example `+919876543210`) * A [Cartesia API key](https://play.cartesia.ai/keys) (looks like `sk_car_...`). If you'd rather use the Cartesia usage included with your Bolna account, you can skip this * One of: `curl`; Python 3.9+ with `requests` (`pip install requests`); or Node.js 18+ for the TypeScript examples, which run with `npx tsx` ## Quick start ### 1. Connect your Cartesia API key In the Bolna dashboard, open **Settings** > [**Integrations**](https://platform.bolna.ai/providers), filter by **TTS**, click **Connect** on the **Cartesia** card, and paste your Cartesia API key. If you'd rather use the Cartesia usage included with your Bolna account, you can skip this step. ### 2. Set environment variables ```bash theme={null} export BOLNA_API_KEY="bn-your-key" export RECIPIENT_PHONE_NUMBER="+919876543210" ``` ### 3. Create an agent with a Sonic voice The `synthesizer` block selects Cartesia. Bolna validates the `model` and `voice_id` pair against its voice catalog, and requires `language` inside `provider_config` for Cartesia. > [tab] cURL > > ```bash theme={null} > curl https://api.bolna.ai/v2/agent \ > -H "Authorization: Bearer $BOLNA_API_KEY" \ > -H "Content-Type: application/json" \ > --data @- <<'EOF' > { > "agent_config": { > "agent_name": "Cartesia Sonic Agent", > "agent_welcome_message": "Hi! This is a test call from a Bolna agent speaking with a Cartesia voice. How is your day going?", > "tasks": [{ > "task_type": "conversation", > "toolchain": { "execution": "sequential", "pipelines": [["transcriber", "llm", "synthesizer"]] }, > "tools_config": { > "synthesizer": { > "provider": "cartesia", > "provider_config": { > "voice": "Brooke - Big Sister", > "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b", > "model": "sonic-3.6", > "language": "en" > }, > "stream": true, > "buffer_size": 250, > "audio_format": "wav" > }, > "llm_agent": { > "agent_type": "simple_llm_agent", > "agent_flow_type": "streaming", > "llm_config": { "provider": "openai", "model": "gpt-5.4-mini", "max_tokens": 150, "temperature": 1 } > }, > "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en", "stream": true, "encoding": "linear16", "sampling_rate": 16000, "endpointing": 250 }, > "input": { "provider": "plivo", "format": "wav" }, > "output": { "provider": "plivo", "format": "wav" } > }, > "task_config": { "call_terminate": 90, "hangup_after_silence": 10 } > }] > }, > "agent_prompts": { > "task_1": { "system_prompt": "You are a friendly assistant making a short test call. Keep every reply under two sentences. Ask how their day is going, thank them, then end the call politely." } > } > } > EOF > ``` > [tab] Python > > Save as `create_agent.py` and run `python create_agent.py`. > > ```python theme={null} > import os > > import requests > > agent_config = { > "agent_name": "Cartesia Sonic Agent", > "agent_welcome_message": "Hi! This is a test call from a Bolna agent speaking with a Cartesia voice. How is your day going?", > "tasks": [{ > "task_type": "conversation", > "toolchain": {"execution": "sequential", "pipelines": [["transcriber", "llm", "synthesizer"]]}, > "tools_config": { > "synthesizer": { > "provider": "cartesia", > "provider_config": { > "voice": "Brooke - Big Sister", > "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b", > "model": "sonic-3.6", > "language": "en", > }, > "stream": True, > "buffer_size": 250, > "audio_format": "wav", > }, > "llm_agent": { > "agent_type": "simple_llm_agent", > "agent_flow_type": "streaming", > "llm_config": {"provider": "openai", "model": "gpt-5.4-mini", "max_tokens": 150, "temperature": 1}, > }, > "transcriber": {"provider": "deepgram", "model": "nova-3", "language": "en", "stream": True, "encoding": "linear16", "sampling_rate": 16000, "endpointing": 250}, > "input": {"provider": "plivo", "format": "wav"}, > "output": {"provider": "plivo", "format": "wav"}, > }, > "task_config": {"call_terminate": 90, "hangup_after_silence": 10}, > }], > } > agent_prompts = { > "task_1": {"system_prompt": "You are a friendly assistant making a short test call. Keep every reply under two sentences. Ask how their day is going, thank them, then end the call politely."} > } > > response = requests.post( > "https://api.bolna.ai/v2/agent", > headers={"Authorization": f"Bearer {os.environ['BOLNA_API_KEY']}"}, > json={"agent_config": agent_config, "agent_prompts": agent_prompts}, > ) > response.raise_for_status() > print(response.json()) > ``` > [tab] TypeScript > > Save as `create-agent.ts` and run `npx tsx create-agent.ts`. > > ```typescript theme={null} > const agentConfig = { > agent_name: "Cartesia Sonic Agent", > agent_welcome_message: "Hi! This is a test call from a Bolna agent speaking with a Cartesia voice. How is your day going?", > tasks: [{ > task_type: "conversation", > toolchain: { execution: "sequential", pipelines: [["transcriber", "llm", "synthesizer"]] }, > tools_config: { > synthesizer: { > provider: "cartesia", > provider_config: { > voice: "Brooke - Big Sister", > voice_id: "e07c00bc-4134-4eae-9ea4-1a55fb45746b", > model: "sonic-3.6", > language: "en", > }, > stream: true, > buffer_size: 250, > audio_format: "wav", > }, > llm_agent: { > agent_type: "simple_llm_agent", > agent_flow_type: "streaming", > llm_config: { provider: "openai", model: "gpt-5.4-mini", max_tokens: 150, temperature: 1 }, > }, > transcriber: { provider: "deepgram", model: "nova-3", language: "en", stream: true, encoding: "linear16", sampling_rate: 16000, endpointing: 250 }, > input: { provider: "plivo", format: "wav" }, > output: { provider: "plivo", format: "wav" }, > }, > task_config: { call_terminate: 90, hangup_after_silence: 10 }, > }], > }; > const agentPrompts = { > task_1: { system_prompt: "You are a friendly assistant making a short test call. Keep every reply under two sentences. Ask how their day is going, thank them, then end the call politely." }, > }; > > async function main() { > const response = await fetch("https://api.bolna.ai/v2/agent", { > method: "POST", > headers: { > Authorization: `Bearer ${process.env.BOLNA_API_KEY}`, > "Content-Type": "application/json", > }, > body: JSON.stringify({ agent_config: agentConfig, agent_prompts: agentPrompts }), > }); > if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`); > console.log(await response.json()); > } > > main(); > ``` Bolna returns the new agent's ID: ```json theme={null} { "agent_id": "123e4567-e89b-12d3-a456-426655440000", "state": "created", "version_id": "9f1d950f-a4ae-4ba6-bf27-19d1b7b8d32e" } ``` Save it for the next step: ```bash theme={null} export BOLNA_AGENT_ID="your-agent-id" ``` ### 4. Place a call Bolna calls `RECIPIENT_PHONE_NUMBER` from its default number. > [tab] cURL > > ```bash theme={null} > curl https://api.bolna.ai/call \ > -H "Authorization: Bearer $BOLNA_API_KEY" \ > -H "Content-Type: application/json" \ > --data @- < { > "agent_id": "$BOLNA_AGENT_ID", > "recipient_phone_number": "$RECIPIENT_PHONE_NUMBER" > } > EOF > ``` > [tab] Python > > Save as `place_call.py` and run `python place_call.py`. > > ```python theme={null} > import os > > import requests > > response = requests.post( > "https://api.bolna.ai/call", > headers={"Authorization": f"Bearer {os.environ['BOLNA_API_KEY']}"}, > json={ > "agent_id": os.environ["BOLNA_AGENT_ID"], > "recipient_phone_number": os.environ["RECIPIENT_PHONE_NUMBER"], > }, > ) > response.raise_for_status() > print(response.json()) > ``` > [tab] TypeScript > > Save as `place-call.ts` and run `npx tsx place-call.ts`. > > ```typescript theme={null} > async function main() { > const response = await fetch("https://api.bolna.ai/call", { > method: "POST", > headers: { > Authorization: `Bearer ${process.env.BOLNA_API_KEY}`, > "Content-Type": "application/json", > }, > body: JSON.stringify({ > agent_id: process.env.BOLNA_AGENT_ID, > recipient_phone_number: process.env.RECIPIENT_PHONE_NUMBER, > }), > }); > if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`); > console.log(await response.json()); > } > > main(); > ``` ```json theme={null} { "message": "done", "status": "queued", "execution_id": "123e4567-e89b-12d3-a456-426614174000" } ``` Your phone rings within a few seconds, and the agent greets you in the Sonic voice. To configure the same agent without code, select Cartesia as the voice provider on the agent's [Languages tab](https://www.bolna.ai/docs/agent-setup/audio-tab) in the Bolna dashboard. ## Configuration Cartesia settings live in `tools_config.synthesizer.provider_config`: | Parameter | Type | Default | Description | | - | - | - | - | | `model` | `string` | Required | `sonic-3.6`, `sonic-3.5`, or `sonic-3` | | `voice` | `string` | Required | Voice display name, for example `"Brooke - Big Sister"` | | `voice_id` | `string` | Required | Voice ID from Bolna's voice catalog (see below) | | `language` | `string` | Required | Language code for synthesis, for example `"en"` or `"hi"` | | `speed` | `number` | `1` | Speaking rate | Bolna validates `model` and `voice_id` together, so resolve a valid pair with [List TTS providers](https://www.bolna.ai/docs/api-reference/voice/get_providers) and [List voices](https://www.bolna.ai/docs/api-reference/voice/get_all) before you create the agent. For tips on picking a voice, see [Choosing a voice](https://docs.cartesia.ai/build-with-cartesia/capability-guides/choosing-a-voice.md). ## Resources * [Bolna Cartesia guide](https://www.bolna.ai/docs/cartesia) * [Bolna create agent API](https://www.bolna.ai/docs/api-reference/agent/v2/create) * [Bolna make call API](https://www.bolna.ai/docs/api-reference/calls/make) * [Bolna provider credentials](https://www.bolna.ai/docs/providers) * [Sonic TTS models](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest.md) * [Cartesia voice library](https://play.cartesia.ai/voices) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.