Agents API Overview

Overview

The Agents API allows you to create and manage AI agents that can handle voice calls and chat conversations. Each agent is a configurable AI assistant that can be customized with specific instructions, tools, and settings.

Agent Types

Voice Agents

Voice agents handle phone-based conversations through Twilio integration and OpenAI's Realtime API. They can be assigned phone numbers and configured with specific voice characteristics.

Key Features:

• Phone number assignment
• Configurable voice settings (voice type, speed, interruption threshold)
• Real-time audio processing
• Tool integration for actions during calls

Chat Agents

Chat agents power website chat widgets, providing text-based conversational interfaces that can be embedded on any website.

Key Features:

• Customizable widget appearance (theme, colors, position)
• Domain restrictions for security
• Embed code generation
• Tool integration for actions during chats

Base URL

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

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

curl -H "x-api-key: YOUR_API_KEY" \
  https://v2.heppu.ai/api/v1/agents

Alternatively, you can use the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://v2.heppu.ai/api/v1/agents

Available Endpoints

Agent Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer Support Agent",
  "type": "voice",
  "status": "active",
  "model": "gpt-realtime-2025-08-28",
  "instructions": "You are a helpful customer support agent...",
  "config": {
    "voice": "sage",
    "speed": 1.0,
    "interruptionThreshold": 0.5
  },
  "tools": [
    {
      "id": "web_search",
      "name": "Web Search",
      "description": "Search the web for information"
    }
  ],
  "phoneNumbers": ["+1234567890"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Common Parameters

Agent Status

• active - Agent is active and can receive requests
• inactive - Agent is disabled and cannot receive requests
• training - Agent is being trained or configured
• deployed - Agent is deployed and in production use

Agent Types

• voice - Voice agent for phone calls
• chat - Chat agent for website widgets

Default Models

• Voice agents: gpt-realtime-2025-08-28 (OpenAI Realtime API)
• Chat agents: gpt-4o (recommended)
• Other chat models: gpt-4o-mini, gpt-4, gpt-4-turbo, gpt-3.5-turbo

Error Handling

The API uses standard HTTP response codes:

• 200 - Success
• 201 - Created successfully
• 400 - Bad request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (access denied)
• 404 - Not found
• 500 - Internal server error

Error responses include details:

{
  "success": false,
  "error": {
    "message": "Agent not found",
    "code": 404
  }
}

Rate Limits

API requests are rate limited per organization. Contact support for rate limit increases.

Best Practices

1. Use descriptive names - Give agents clear, descriptive names that indicate their purpose
2. Provide clear instructions - Write detailed instructions for agent behavior and responses
3. Test before deploying - Use the test interface to verify agent behavior before production use
4. Monitor usage - Track agent metrics and conversations to optimize performance
5. Keep tools minimal - Only enable the tools your agent needs for its specific use case
6. Use appropriate models - Choose models based on your use case (realtime for voice, GPT-4o for complex chat)

Next Steps