Developer API v1.0

Getting Started with CallWhiz AI API

The CallWhiz AI Developer API enables you to build powerful conversational AI voice applications. Create voice agents, manage calls, and integrate voice AI into your products with our comprehensive REST API.

Base URL

http://localhost:9000/v1

Quick Start

1. Get your API key from the dashboard
2. Install our SDK or use HTTP client
3. Make your first API call
4. Build amazing voice applications!

Key Features

• RESTful API design
• Comprehensive webhooks
• Real-time voice calls
• Enterprise-ready security

Quick Example

Create your first agent with curl:

bash

# For local development
curl -X POST http://localhost:9000/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "model": "nano",
    "voice": "Olivia",
    "prompt": "You are a helpful assistant. Be friendly and concise."
  }'

# For production
curl -X POST https://developer.callwhiz.ai/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "model": "nano",
    "voice": "Olivia",
    "prompt": "You are a helpful assistant. Be friendly and concise."
  }'

Note: SDKs for JavaScript and Python are coming soon. For now, use the REST API directly with curl or your favorite HTTP client.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header using Bearer authentication:

Example Request with Authentication

bash

# Using your API key
curl -X GET http://localhost:9000/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef"

API Key Types

• cw_live_* - Production API keys

Security Best Practices

• Never expose API keys in client-side code
• Use environment variables for key storage
• Rotate keys regularly
• Use separate keys for development and production

Available Models

Choose the right model for your use case. All models support function calls, allowing your agents to interact with external services through webhooks.

Model	Description	Speed	Cost	Function Calls	Status
nano	Fastest and most cost-effective. Perfect for simple conversations and quick responses.	Fastest	₹5/min	✓ Supported	Available
lite	More powerful with balanced cost. Ideal for complex conversations and business logic.	Fast	₹7/min	✓ Supported	Available
pro	Real-time conversational model with lowest latency. Perfect for natural, flowing conversations.	Real-time	₹10/min	✓ Supported	Available
gpt-realtime	OpenAI's most advanced real-time voice model with natural interruption handling and emotional intelligence.	Real-time	₹15/min	✓ Supported	Available

Choosing the Right Model

Use nano when: You need fast responses, simple conversations, or cost is a primary concern. Great for appointment confirmations, basic Q&A, or simple data collection.

Use lite when: You need more sophisticated conversations, complex business logic, or multi-turn dialogues. Perfect for customer support, sales agents, or detailed information gathering.

Use pro when: You need the most natural, real-time conversations with minimal latency. Ideal for high-stakes customer interactions or when conversation quality is paramount.

Use gpt-realtime when: You require the most advanced conversational AI with natural interruption handling, emotional intelligence, and the highest quality voice interactions. Best for premium customer experiences and complex real-time scenarios.

Model Usage Examples

Using nano model for a simple agent:

bash

curl -X POST http://localhost:9000/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminder Bot",
    "model": "nano",
    "voice": "Olivia",
    "prompt": "You are calling to remind about an appointment. Be brief and friendly.",
    "webhook_ids": ["func_webhook_calendar123"]
  }'

Using lite model for a complex support agent:

bash

curl -X POST http://localhost:9000/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Support Agent",
    "model": "lite",
    "voice": "Brian",
    "prompt": "You are a technical support agent. Help customers troubleshoot issues, look up their account details, and create support tickets as needed.",
    "webhook_ids": ["func_webhook_crm456", "func_webhook_ticket789", "func_webhook_kb123"]
  }'

Using pro model for real-time conversations (coming soon):

bash

# Available next week
curl -X POST http://localhost:9000/v1/agents \
  -H "Authorization: Bearer cw_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Sales Consultant",
    "model": "pro",
    "voice": "Sarah",
    "prompt": "You are a premium sales consultant. Engage in natural, flowing conversations to understand customer needs and provide personalized solutions.",
    "webhook_ids": ["func_webhook_crm456", "func_webhook_inventory789", "func_webhook_pricing123"]
  }'

Available Voices

Select your language, model, and accent to see available voices. Use only the voice name when creating or updating agents.

Supported Language Codes

European Languages

en - English (with accents)
es - Spanish
fr - French
de - German
it - Italian
pt - Portuguese
ru - Russian
pl - Polish

Asian Languages

hi - Hindi
te - Telugu
ta - Tamil
kn - Kannada
ml - Malayalam
mr - Marathi
bn - Bengali
gu - Gujarati

Other Languages

zh - Chinese
ja - Japanese
ko - Korean
ar - Arabic
tr - Turkish
id - Indonesian
th - Thai
vi - Vietnamese

Note: Only English (en) supports accent selection. Accents include: American, British, Australian, Indian, Canadian, Irish, Scottish, and South African.

Loading voices...

Function Webhooks

Create custom functions that your agents can call during conversations. These webhooks act as external tools your agent can use to fetch data, perform actions, or integrate with third-party services. Supports full JSON Schema Draft 7 and OpenAPI 3.0 parameter definitions including nested objects, arrays, enums, validation constraints, and more.

What are Function Webhooks?

Function webhooks are HTTP endpoints that agents can call as functions during conversations. They enable your agents to:

Look up customer information from your CRM
Check real-time data (weather, stock prices, etc.)
Perform actions (send emails, create tickets, etc.)
Integrate with any external API or service

POST/user-webhooks

Create a function webhook that agents can use

GET/user-webhooks

List all your function webhooks

GET/user-webhooks/{webhook_id}

Get details of a specific function webhook

PUT/user-webhooks/{webhook_id}

Update an existing function webhook

DELETE/user-webhooks/{webhook_id}

Delete a function webhook. Note: You cannot delete webhooks that are currently in use by active agents.

Voice Agents

Create and manage AI voice agents that can handle conversations naturally. Configure voice, personality, and behavior.

POST/agents

Create a new AI voice agent with custom configuration

GET/agents

Get a list of all voice agents in your account

GET/agents/{agent_id}

Retrieve details of a specific voice agent

PUT/agents/{agent_id}

Update an existing agent's configuration

DELETE/agents/{agent_id}

Delete (deactivate) a voice agent

Call Management

Initiate outbound calls, track call status, and access call recordings and transcripts.

POST/calls

Start an outbound call using a specific voice agent

GET/calls/{call_id}/transcript

Retrieve the conversation transcript for a completed call

Phone Numbers

Get a list of phone numbers assigned to your account with their channel limits. These phone numbers can be used for making outbound calls.

GET/phone-numbers

Get all phone numbers assigned to your account

Call History

Access your complete call history with secure encrypted IDs for each call record.

About Call History

The Call History API provides access to:

Complete call records with secure encrypted IDs
Conversation transcripts for AI calls
Call duration, status, and metadata
Default limit of 10 records, newest first
Support for filtering by call type, status, date range, and more

GET/call-history

Get paginated call history with filters and encrypted IDs

GET/call-history/{encrypted_call_id}

Get detailed information about a specific call using encrypted ID

GET/call-history/{encrypted_call_id}/transcript

Get the conversation transcript for a completed AI call

Field Descriptions

Call History Fields

id:: Encrypted unique identifier for the call (use this for all API operations)
call_type:: Type of call: 'manual', 'ai', or 'campaign'
direction:: Call direction: 'inbound' or 'outbound'
destination:: Phone number that was called
did:: Your CallWhiz AI phone number used for the call
duration:: Call duration in MM:SS or HH:MM:SS format
status:: Call status: 'Completed', 'Failed', 'In Progress', 'No Answer', 'Busy'
created_at:: When the call was initiated (ISO 8601)
has_transcript:: Boolean indicating if transcript is available (AI calls only)
agent_name:: Name of the AI agent or 'Manual Call'
contact_name:: Name of the contact if available from CRM
medium:: Call medium: 'web', 'phone_line', or 'whatsapp'