Quick Start

Get up and running with the Vocobase V2 API. By the end of this guide, you will have created a voice agent and initiated your first outbound call.

Prerequisites

A Vocobase account (get set up)
Your API key (format: rg_live_xxxx)
At least one telephony provider configured and allowed for your account

Get your API key

Log in to the Vocobase Dashboard and navigate to API Keys. Create a new key and copy it immediately — it is only shown once.Your key looks like this:

rg_live_abc123def456ghi789jkl012

Store your API key securely. It cannot be retrieved after creation.

Test your connection

Verify your API key works by fetching your account configuration:

curl -X GET https://api.vocobase.com/api/v2/config \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

const response = await fetch("https://api.vocobase.com/api/v2/config", {
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012"
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.vocobase.com/api/v2/config",
    headers={"Authorization": "Bearer rg_live_abc123def456ghi789jkl012"}
)
print(response.json())

You should receive a response with your account configuration:

{
  "success": true,
  "data": {
    "name": "acme-corp",
    "display_name": "Acme Corporation",
    "agent_limit": 10,
    "current_agent_count": 0,
    "status": "active",
    ...
  }
}

Create an agent

Create your first voice agent. The voice_id is the catalog id returned by GET /agent/voices — fetch it first and pick a row that matches the tier, language, and gender you want. Use GET /agent/voice-tiers to list supported tiers, then filter the catalog with GET /agent/voices?tier=va-1.

curl -X POST https://api.vocobase.com/api/v2/agent \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Sales Assistant",
    "prompt": "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
    "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
    "agent_type": "outbound",
    "intro_message": "Hello! Thanks for taking my call. How can I help you today?"
  }'

const response = await fetch("https://api.vocobase.com/api/v2/agent", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_name: "Sales Assistant",
    prompt: "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
    voice_id: "b49e0d0f-2219-4425-a765-1efd32beb509",
    agent_type: "outbound",
    intro_message: "Hello! Thanks for taking my call. How can I help you today?"
  })
});
const data = await response.json();
console.log(data.data.id); // Save this agent ID

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/agent",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "agent_name": "Sales Assistant",
        "prompt": "You are a friendly sales assistant for Acme Corp. Help callers understand our products and answer their questions.",
        "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
        "agent_type": "outbound",
        "intro_message": "Hello! Thanks for taking my call. How can I help you today?"
    }
)
data = response.json()
print(data["data"]["id"])  # Save this agent ID

The response includes your new agent’s ID:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "status": "active",
    ...
  }
}

Save the id from the response - you will need it to start calls. On supported Plivo and Vobiz accounts, agents also accept optional voicemail_detection_enabled and voicemail_message fields for carrier-side voicemail handling.

Agent languages

By default an agent speaks the language of the voice you picked. To let it understand and reply in more than one language, pass spoken_languages on create or update:

{ "spoken_languages": ["en", "hi"] }

Allowed codes: en, hinglish, hi, mr, te, ta, kn, ml, gu, pa, bn. Two rules apply:

At most two languages, and at most one Indian language (hi, mr, te, ta, kn, ml, gu, pa, bn).
hinglish only pairs with en or hi — it already contains Hindi, so pairing it with another Indian language would break rule 1 indirectly.

Value	Valid	Why
`["en", "hi"]`	✅	English plus one Indian language
`["en", "hinglish"]`	✅	Hinglish pairs with English
`["hi", "hinglish"]`	✅	Hinglish pairs with Hindi
`["en", "te"]`	✅	English plus one Indian language
`["te"]`	✅	A single language is always fine
`["mr", "te"]`	❌	Two Indian languages
`["te", "hi"]`	❌	Two Indian languages
`["mr", "hi"]`	❌	Two Indian languages
`["hinglish", "mr"]`	❌	Hinglish only pairs with `en` or `hi`

An invalid combination returns 400 with a VALIDATION_ERROR. Omit the field to leave it unchanged on update, or send [] to clear it back to the voice’s own language.

Make your first call

Initiate an outbound call using the agent you just created. Replace the agent_id with the ID from the previous step. If your account has multiple active connections for the selected provider, include connection_id from GET /api/v2/telephony/connections.

curl -X POST https://api.vocobase.com/api/v2/calls/start \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_number": "+919876543210",
    "provider": "twilio",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

const response = await fetch("https://api.vocobase.com/api/v2/calls/start", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    to_number: "+919876543210",
    provider: "twilio",
    connection_id: "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/calls/start",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "to_number": "+919876543210",
        "provider": "twilio",
        "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
    }
)
print(response.json())

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "twilio",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

The from_number is resolved from the selected provider connection and returned in the response. The call is placed asynchronously. Set up webhooks to receive live call status updates plus the final transcript and recording URL.

Next steps

Authentication

Learn about API key formats, rate limits, and error handling.

Configure Webhooks

Receive live call status updates and final session results.

Twilio Setup

Configure Twilio for outbound calling.

API Reference

Explore the full API reference.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Quick Start

Quick Start

Prerequisites

Agent languages

Next steps

Authentication

Configure Webhooks

Twilio Setup

API Reference

​Quick Start

​Prerequisites

​Agent languages

​Next steps

Authentication

Configure Webhooks

Twilio Setup

API Reference

Quick Start

Prerequisites

Agent languages

Next steps