Voice.ai Agents

Build the best conversational AI voice agents with Voice.ai's Agent API.

✨ Features

Agent Management - Create, update, and delete voice agents
One-Click Deploy - Deploy agents for phone calls instantly
Knowledge Base - RAG-powered agents with custom knowledge
MCP Integration - Connect agents to external tools via MCP
Phone Numbers - Manage inbound/outbound phone numbers
Analytics - Track call history and agent performance

⚙️ Configuration

Get Your API Key

Go to Voice.ai Developer Dashboard
Sign in or create an account
Generate a new API key
Copy and save it securely

Set Up Authentication (3 Methods)

Method 1: Environment Variable (Recommended)

export VOICE_AI_API_KEY="your-api-key-here"

Method 2: .env File

# Create .env file in project root
echo 'VOICE_AI_API_KEY=your-api-key-here' >> .env

Method 3: OpenClaw Config

{
  "skills": {
    "voice.ai-voice-agents": {
      "api_key": "your-api-key-here"
    }
  }
}

🔐 Before Any Operation

Important: Always verify authentication before running any commands.

# 1. Check if API key is set
echo $VOICE_AI_API_KEY

# 2. Test connection (list agents)
node scripts/agent.js list

# 3. If errors, re-export your key
export VOICE_AI_API_KEY="your-api-key-here"

Silent Initialization

The SDK automatically initializes when you run any command. No manual setup required after setting the API key.

🚀 Quick Start

export VOICE_AI_API_KEY="your-api-key"

# Create an agent
node scripts/agent.js create --name "Support Bot" --prompt "You are a helpful assistant"

# List all agents
node scripts/agent.js list

# Deploy an agent
node scripts/agent.js deploy --id <agent_id>

🤖 Agent Configuration

| Parameter | Default | Description | |------------------------|---------|--------------------------------------| | llm_model | gemini-2.5-flash-lite | LLM model for responses | | llm_temperature | 0.7 | Response creativity (0-2) | | max_call_duration | 900 | Max call length in seconds | | allow_interruptions | true | Let users interrupt agent | | auto_noise_reduction | true | Filter background noise |

🎙️ TTS Voice Settings

| Parameter | Default | Description | |-------------|---------|--------------------------------| | voice_id | - | Voice ID for agent speech | | model | auto | TTS model (auto-selected) | | language | en | Language code | | temperature | 1.0 | Voice expressiveness (0-2) | | top_p | 0.8 | Sampling parameter (0-1) |

🌍 Supported Languages

auto, en, ca, sv, es, fr, de, it, pt, pl, ru, nl

💻 CLI Usage

# Create a new agent
node scripts/agent.js create --name "My Agent" --prompt "System prompt here" --greeting "Hello!"

# List all agents
node scripts/agent.js list

# Get agent details
node scripts/agent.js get --id <agent_id>

# Update an agent
node scripts/agent.js update --id <agent_id> --prompt "New prompt"

# Deploy an agent
node scripts/agent.js deploy --id <agent_id>

# Pause an agent
node scripts/agent.js pause --id <agent_id>

# Delete an agent
node scripts/agent.js delete --id <agent_id>

🤖 OpenClaw Integration

JSON Configuration

{
  "name": "voice.ai-voice-agents",
  "enabled": true,
  "config": {
    "api_key": "${VOICE_AI_API_KEY}",
    "default_model": "gemini-2.5-flash-lite",
    "auto_deploy": false
  }
}

Chat Triggers

OpenClaw automatically activates this skill when you mention:

"voice agent", "voice bot", "phone agent"
"create agent", "deploy agent", "list agents"
"Voice.ai", "voice ai"

🗣️ User-Friendly Language

| When User Says... | Skill Does... | |-------------------|---------------| | "Create a support agent" | Creates agent with support-focused prompt | | "Show my agents" | Lists all agents with status | | "Deploy the agent" | Deploys agent for phone calls | | "Update the greeting" | Updates agent greeting message | | "Delete the test agent" | Deletes specified agent | | "What agents do I have?" | Lists agents in friendly format | | "Make an FAQ bot" | Creates agent with FAQ template | | "Connect to my MCP server" | Configures MCP integration |

📁 Project Files

voice-ai-agents/
├── SKILL.md                    # This documentation
├── voice-ai-agents.yaml        # Skill configuration
├── voice-ai-agents-sdk.js      # JavaScript SDK
└── scripts/
    └── agent.js                # CLI tool

| File | Purpose | |------|---------| | SKILL.md | Documentation and OpenClaw skill definition | | voice-ai-agents.yaml | API config, models, defaults | | voice-ai-agents-sdk.js | Full SDK with all API methods | | scripts/agent.js | Command-line interface |

❌ Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Invalid or missing API key | Check VOICE_AI_API_KEY is set correctly | | 403 Forbidden | API key lacks permissions | Generate new key with proper scopes | | 404 Not Found | Agent ID doesn't exist | Run list to get valid agent IDs | | 429 Too Many Requests | Rate limit exceeded | Wait 60 seconds and retry | | 500 Server Error | Voice.ai API issue | Check status page | | ENOTFOUND | Network error | Check internet connection | | Agent not deployed | Agent exists but not active | Run deploy --id <agent_id> |

Graceful Error Messages

The SDK provides user-friendly error messages:

❌ Authentication failed. Please check your API key.
   Get one at: https://voice.ai/app/dashboard/developers

❌ Agent "support-bot" not found. 
   Run 'node scripts/agent.js list' to see available agents.

❌ Rate limit reached. Please wait 60 seconds before retrying.

📝 Triggers

These phrases activate the Voice.ai Agents skill in OpenClaw:

| Category | Trigger Phrases | |----------|-----------------| | Create | "create voice agent", "make a phone bot", "new agent" | | List | "show agents", "list my agents", "what agents exist" | | Deploy | "deploy agent", "activate agent", "start the bot" | | Update | "update agent", "change prompt", "edit greeting" | | Delete | "delete agent", "remove bot", "destroy agent" | | Info | "agent details", "show agent", "get agent info" |

🔗 MCP Server Integration

Connect your agent to external tools:

const agent = await client.createAgent({
  name: "MCP Agent",
  config: {
    prompt: "You can use tools to help users",
    mcp_servers: [{
      name: "my-tools",
      url: "https://my-server.com/mcp",
      auth_type: "bearer_token",
      auth_token: "secret"
    }]
  }
});

📚 Knowledge Base (RAG)

Add custom knowledge to your agent:

# Create agent with knowledge base
node scripts/agent.js create --name "FAQ Bot" --kb-id 123

🔗 Links

📋 Changelog

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-01-31 | Initial release with full agent management |

Made with ❤️ by Nick Gill