Bolna + Cartesia

Last verified: 2026-10-30

Overview

Bolna 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 as the agent’s synthesizer to speak every reply with a Cartesia voice.

Prerequisites

A Bolna account at platform.bolna.ai with wallet credits, since calls consume credits
A Bolna API key (BOLNA_API_KEY) from Generate an API key
A phone number to call, in E.164 format (for example +919876543210)
A Cartesia API key (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

Connect your Cartesia API key

In the Bolna dashboard, open Settings > Integrations, 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.

Set environment variables

export BOLNA_API_KEY="bn-your-key"
export RECIPIENT_PHONE_NUMBER="+919876543210"

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.

cURL
Python
TypeScript

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

Save as create_agent.py and run python create_agent.py.

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())

Save as create-agent.ts and run npx tsx create-agent.ts.

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:

{
  "agent_id": "123e4567-e89b-12d3-a456-426655440000",
  "state": "created",
  "version_id": "9f1d950f-a4ae-4ba6-bf27-19d1b7b8d32e"
}

Save it for the next step:

export BOLNA_AGENT_ID="your-agent-id"

Place a call

Bolna calls RECIPIENT_PHONE_NUMBER from its default number.

cURL
Python
TypeScript

curl https://api.bolna.ai/call \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "agent_id": "$BOLNA_AGENT_ID",
  "recipient_phone_number": "$RECIPIENT_PHONE_NUMBER"
}
EOF

Save as place_call.py and run python place_call.py.

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())

Save as place-call.ts and run npx tsx place-call.ts.

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();

{ "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 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 and List voices before you create the agent. For tips on picking a voice, see Choosing a voice.

Overview

Start building

Developers

Integrations

Overview

Prerequisites

Quick start

Connect your Cartesia API key

Set environment variables

Create an agent with a Sonic voice

Place a call

Configuration

Resources

​Overview

​Prerequisites

​Quick start

Connect your Cartesia API key

Set environment variables

Create an agent with a Sonic voice

Place a call

​Configuration

​Resources

Overview

Prerequisites

Quick start

Configuration

Resources