Heppu AI API

The Heppu AI API enables you to build, deploy, and manage intelligent AI agents that can handle voice calls and chat conversations. Perfect for customer support automation, lead qualification, appointment scheduling, and more.

What You Can Build

Key Features

• Multi-Channel Support: Handle voice calls via Twilio and text conversations via chat widget
• Custom Tool Integration: Connect your agents to CRMs, databases, and third-party APIs
• Real-time Communication: WebSocket support for live conversation updates
• Enterprise Security: Organization-scoped access, API key management, and secure authentication
• Conversation Intelligence: Automatic logging, transcription, and sentiment analysis
• Webhook Events: Get notified of call completions, messages, and agent interactions

Base URL

All API requests should be made to:

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

Authentication

The Heppu API uses API keys to authenticate requests. You can create and manage API keys from your organization settings.

Include your API key in every request using either:

Header: x-api-key (Recommended)

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

Header: Authorization: Bearer

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

Learn more about authentication →

Response Format

All successful API responses follow this structure:

{
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-12-01T12:00:00Z",
    "message": "Optional success message"
  }
}

Error responses use a different format:

{
  "error": {
    "message": "Descriptive error message",
    "status": 404,
    "timestamp": "2024-12-01T12:00:00Z"
  }
}

Learn more about error handling →

Rate Limits

The API implements rate limiting to ensure fair usage:

• Standard Plan: 100 requests/minute, 10,000 requests/day
• Professional Plan: 500 requests/minute, 100,000 requests/day
• Enterprise Plan: Custom limits based on your needs

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1638360000

API Versioning

The current API version is v1. The version is included in the base URL:

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

We maintain backward compatibility within major versions. Breaking changes will only be introduced in new major versions (e.g., v2), and you'll receive advance notice before deprecation.

Common Patterns

Organization Scoping

All resources (agents, calls, conversations) are scoped to your organization. The API automatically uses your API key to determine the organization context.

# This returns agents for your organization only
curl https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: your_api_key_here"

Pagination

List endpoints support pagination using page and limit query parameters:

curl "https://v2.heppu.ai/api/v1/agents?page=1&limit=20" \
  -H "x-api-key: your_api_key_here"

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Filtering & Sorting

Many endpoints support filtering and sorting:

# Filter by status
curl "https://v2.heppu.ai/api/v1/calls?status=completed" \
  -H "x-api-key: your_api_key_here"

# Sort by creation date
curl "https://v2.heppu.ai/api/v1/agents?sortBy=createdAt&order=desc" \
  -H "x-api-key: your_api_key_here"

Webhooks

Subscribe to events in your Heppu account using webhooks. We'll send HTTP POST requests to your specified endpoint when events occur.

Available Events:

• call.completed - A voice call has finished
• call.failed - A voice call encountered an error
• chat.message.received - A new chat message was received

Learn more about webhooks →

Getting Started

Ready to start making calls with your AI agents?

Need Help?

• Documentation: Browse our comprehensive guides and API reference
• Support: Email us at support@heppu.ai

Next Steps

1. Create an Account - Sign up at v2.heppu.ai and create your organization
2. Generate API Key - Navigate to API Keys and create a new key
3. Schedule Your First Call - Use the Schedule Call API to make your first outbound call
4. Set Up Webhooks - Configure webhooks to receive call and chat notifications