Create Agent

POST /api/v1/agents

Create a new agent in your organization. Agents can be either voice agents for phone calls or chat agents for website widgets.

Endpoint

POST https://v2.heppu.ai/api/v1/agents

Authentication

Requires API key authentication via x-api-key or Authorization header.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent name (max 255 characters)
`type`	string	Yes	Agent type: `voice` or `chat`
`model`	string	No	OpenAI model identifier. Defaults: voice = `gpt-realtime-2025-08-28`, chat = `gpt-4o`
`instructions`	string	No	Agent behavior instructions (system prompt)
`config`	object	No	Type-specific configuration (voice settings or widget settings)
`toolIds`	array	No	Array of tool IDs to enable for this agent

Config Object

Voice Agent Config

{
  "voice": "sage",
  "speed": 1.0,
  "interruptionThreshold": 0.5,
  "timeout": 30
}

Field	Type	Description
`voice`	string	OpenAI voice: `ash`, `ballad`, `coral`, `sage`, `verse`, `shimmer`
`speed`	number	Speech speed (0.5 - 2.0)
`interruptionThreshold`	number	How easily user can interrupt (0.0 - 1.0)
`timeout`	number	Call timeout in seconds

Chat Agent Config

{
  "theme": "dark",
  "primaryColor": "#3B82F6",
  "position": "bottom-right",
  "greeting": "Hello! How can I help you today?",
  "placeholder": "Type your message...",
  "allowedDomains": ["example.com", "www.example.com"]
}

Field	Type	Description
`theme`	string	Widget theme: `light` or `dark`
`primaryColor`	string	Primary color (hex format)
`position`	string	Widget position: `bottom-right`, `bottom-left`, `top-right`, `top-left`
`greeting`	string	Initial greeting message
`placeholder`	string	Input placeholder text
`allowedDomains`	array	Array of allowed domains (empty = all domains)

Response

Returns the created agent object with a 201 status code.

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "type": "voice",
    "model": "gpt-realtime-2025-08-28",
    "instructions": "You are a helpful customer support agent...",
    "status": "active",
    "config": {
      "voice": "sage",
      "speed": 1.0,
      "interruptionThreshold": 0.5
    },
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "message": "Agent created successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "message": "Missing required fields: name and type are required",
    "code": 400
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid type. Must be 'voice' or 'chat'",
    "code": 400
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": 401
  }
}

Examples

cURL

# Create a voice agent
curl -X POST "https://v2.heppu.ai/api/v1/agents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "type": "voice",
    "instructions": "You are a helpful customer support agent. Be polite and professional.",
    "config": {
      "voice": "sage",
      "speed": 1.0,
      "interruptionThreshold": 0.5
    },
    "toolIds": ["web_search", "calendar"]
  }'

# Create a chat agent
curl -X POST "https://v2.heppu.ai/api/v1/agents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Chat Assistant",
    "type": "chat",
    "model": "gpt-4o",
    "instructions": "You are a friendly website assistant. Help users navigate the site and answer questions.",
    "config": {
      "theme": "dark",
      "primaryColor": "#3B82F6",
      "position": "bottom-right",
      "greeting": "Hello! How can I help you today?",
      "placeholder": "Type your message...",
      "allowedDomains": ["example.com"]
    },
    "toolIds": ["calculator", "web_search"]
  }'

JavaScript

// Create a voice agent
const createVoiceAgent = async () => {
  const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Customer Support Agent',
      type: 'voice',
      instructions: 'You are a helpful customer support agent.',
      config: {
        voice: 'sage',
        speed: 1.0,
        interruptionThreshold: 0.5
      },
      toolIds: ['web_search', 'calendar']
    })
  });

  const result = await response.json();
  console.log('Agent created:', result.data.id);
  return result.data;
};

// Create a chat agent
const createChatAgent = async () => {
  const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Website Chat Assistant',
      type: 'chat',
      model: 'gpt-4o',
      instructions: 'You are a friendly website assistant.',
      config: {
        theme: 'dark',
        primaryColor: '#3B82F6',
        position: 'bottom-right',
        greeting: 'Hello! How can I help you today?',
        placeholder: 'Type your message...'
      },
      toolIds: ['calculator']
    })
  });

  const result = await response.json();
  return result.data;
};

Python

import requests
import json

# Create a voice agent
def create_voice_agent():
    response = requests.post(
        'https://v2.heppu.ai/api/v1/agents',
        headers={
            'x-api-key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'name': 'Customer Support Agent',
            'type': 'voice',
            'instructions': 'You are a helpful customer support agent.',
            'config': {
                'voice': 'sage',
                'speed': 1.0,
                'interruptionThreshold': 0.5
            },
            'toolIds': ['web_search', 'calendar']
        }
    )

    result = response.json()
    print(f"Agent created: {result['data']['id']}")
    return result['data']

# Create a chat agent
def create_chat_agent():
    response = requests.post(
        'https://v2.heppu.ai/api/v1/agents',
        headers={
            'x-api-key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'name': 'Website Chat Assistant',
            'type': 'chat',
            'model': 'gpt-4o',
            'instructions': 'You are a friendly website assistant.',
            'config': {
                'theme': 'dark',
                'primaryColor': '#3B82F6',
                'position': 'bottom-right',
                'greeting': 'Hello! How can I help you today?',
                'placeholder': 'Type your message...',
                'allowedDomains': ['example.com']
            },
            'toolIds': ['calculator', 'web_search']
        }
    )

    return response.json()['data']

# Usage
agent = create_voice_agent()

Node.js (with TypeScript)

interface CreateAgentRequest {
  name: string;
  type: 'voice' | 'chat';
  model?: string;
  instructions?: string;
  config?: Record<string, any>;
  toolIds?: string[];
}

interface Agent {
  id: string;
  name: string;
  type: 'voice' | 'chat';
  model: string;
  instructions: string;
  status: string;
  config: Record<string, any>;
  createdAt: string;
}

async function createAgent(
  data: CreateAgentRequest
): Promise<Agent> {
  const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HEPPU_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const result = await response.json();
  return result.data;
}

// Usage - Create voice agent
const voiceAgent = await createAgent({
  name: 'Customer Support Agent',
  type: 'voice',
  instructions: 'You are a helpful customer support agent.',
  config: {
    voice: 'sage',
    speed: 1.0,
    interruptionThreshold: 0.5,
  },
  toolIds: ['web_search', 'calendar'],
});

// Usage - Create chat agent
const chatAgent = await createAgent({
  name: 'Website Chat Assistant',
  type: 'chat',
  model: 'gpt-4o',
  instructions: 'You are a friendly website assistant.',
  config: {
    theme: 'dark',
    primaryColor: '#3B82F6',
    position: 'bottom-right',
    greeting: 'Hello! How can I help you today?',
  },
  toolIds: ['calculator'],
});

Available Models

Voice Agents

gpt-realtime-2025-08-28 (default) - OpenAI Realtime API for voice conversations

Chat Agents

gpt-4o (default, recommended) - Most capable model for complex conversations
gpt-4o-mini (faster, lower cost) - Fast and cost-effective
gpt-4 - Original GPT-4 model
gpt-4-turbo - High performance model
gpt-3.5-turbo - Fast and efficient

Available Voices (Voice Agents)

ash - Conversational and friendly
ballad - Warm and expressive
coral - Clear and professional
sage - Calm and knowledgeable (default)
verse - Energetic and enthusiastic
shimmer - Soft and soothing

Common Tool IDs

web_search - Search the web for information
calculator - Perform mathematical calculations
calendar - Manage calendar events
email - Send emails
crm - CRM integration
weather - Get weather information
sms - Send SMS messages

Note: Available tools depend on your organization's subscription and enabled features.

Notes

New agents are created with status: "active" by default
If model is not provided, defaults are used based on agent type
If instructions is not provided, it defaults to an empty string
The agent ID is automatically generated as a UUID
Tool IDs are validated - only existing tools will be assigned
Invalid tool IDs are silently ignored
Empty toolIds array or omitting it creates an agent with no tools
Voice agent config is optional - defaults will be used if not provided
Chat agent config is optional - default widget settings will be used
Allowed domains for chat agents: empty array = all domains allowed

Best Practices

Detailed Instructions: Provide comprehensive instructions for agent behavior
Test Before Deploy: Test agents thoroughly before assigning phone numbers or deploying to production
Start Simple: Begin with basic configuration and iterate based on testing
Tool Selection: Only enable tools your agent needs for its specific use case
Voice Selection: Test different voices to find the best fit for your use case
Domain Restrictions: Use allowedDomains for chat agents to prevent unauthorized use
Model Selection: Use GPT-4o for complex reasoning, GPT-4o Mini for simple tasks

List Agents - Get all agents
Get Agent - Get detailed agent information
Update Agent - Update agent configuration
Delete Agent - Delete an agent

Create Agent

On this page