Quick Start Guide

Get your first AI agent up and running in just 5 minutes. This guide walks you through creating an API key, making your first request, and setting up a simple voice agent.

Prerequisites

Before you begin, make sure you have:

A Heppu AI account (sign up here)
An organization created in your account
cURL, Node.js, or Python installed on your machine

Don't have an account? Sign up at v2.heppu.ai to get started with our free tier.

Step 1: Get Your API Key

Log in to your Heppu dashboard
Navigate to Organization → API Keys
Click Create API Key
Give your key a descriptive name (e.g., "Development Key")
Copy the key and store it securely

API keys are only shown once! Save your key in a secure location like a password manager or environment variable.

# Store your API key as an environment variable
export HEPPU_API_KEY="your_api_key_here"

Step 2: Make Your First Request

Let's verify your API key works by fetching your organization's agents:

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

const fetch = require('node-fetch');

const apiKey = process.env.HEPPU_API_KEY;

async function getAgents() {
  const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
    headers: {
      'x-api-key': apiKey
    }
  });

  const data = await response.json();
  console.log(data);
}

getAgents();

import os
import requests

api_key = os.environ.get('HEPPU_API_KEY')

response = requests.get(
    'https://v2.heppu.ai/api/v1/agents',
    headers={'x-api-key': api_key}
)

print(response.json())

Expected Response:

{
  "data": [],
  "meta": {
    "timestamp": "2024-12-01T12:00:00Z",
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0
  }
}

If you see a response with "data": [], congratulations! Your API key is working correctly.

Step 3: Create Your First Agent

Now let's create a simple customer support agent:

curl -X POST https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: $HEPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Helpful customer support assistant",
    "systemPrompt": "You are a friendly customer support agent. Help customers with their questions and direct them to the right resources.",
    "voice": "alloy",
    "model": "gpt-4-turbo",
    "temperature": 0.7
  }'

const fetch = require('node-fetch');

const apiKey = process.env.HEPPU_API_KEY;

async function createAgent() {
  const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Support Agent',
      description: 'Helpful customer support assistant',
      systemPrompt: 'You are a friendly customer support agent. Help customers with their questions and direct them to the right resources.',
      voice: 'alloy',
      model: 'gpt-4-turbo',
      temperature: 0.7
    })
  });

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

createAgent();

import os
import requests

api_key = os.environ.get('HEPPU_API_KEY')

agent_data = {
    'name': 'Support Agent',
    'description': 'Helpful customer support assistant',
    'systemPrompt': 'You are a friendly customer support agent. Help customers with their questions and direct them to the right resources.',
    'voice': 'alloy',
    'model': 'gpt-4-turbo',
    'temperature': 0.7
}

response = requests.post(
    'https://v2.heppu.ai/api/v1/agents',
    headers={'x-api-key': api_key},
    json=agent_data
)

print('Agent created:', response.json())

Expected Response:

{
  "data": {
    "id": "agent_abc123",
    "name": "Support Agent",
    "description": "Helpful customer support assistant",
    "systemPrompt": "You are a friendly customer support agent...",
    "voice": "alloy",
    "model": "gpt-4-turbo",
    "temperature": 0.7,
    "status": "active",
    "organizationId": "org_xyz789",
    "createdAt": "2024-12-01T12:00:00Z",
    "updatedAt": "2024-12-01T12:00:00Z"
  },
  "meta": {
    "timestamp": "2024-12-01T12:00:00Z",
    "message": "Agent created successfully"
  }
}

Save the agent ID (agent_abc123) - you'll need it for the next steps!

Step 4: Test Your Agent

Option A: Chat Interface

Test your agent using the chat API:

curl -X POST https://v2.heppu.ai/api/v1/chat/send \
  -H "x-api-key: $HEPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "message": "Hello! I need help with my account.",
    "sessionId": "test-session-1"
  }'

async function testAgent(agentId) {
  const response = await fetch('https://v2.heppu.ai/api/v1/chat/send', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agentId: agentId,
      message: 'Hello! I need help with my account.',
      sessionId: 'test-session-1'
    })
  });

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

testAgent('agent_abc123');

def test_agent(agent_id):
    response = requests.post(
        'https://v2.heppu.ai/api/v1/chat/send',
        headers={'x-api-key': api_key},
        json={
            'agentId': agent_id,
            'message': 'Hello! I need help with my account.',
            'sessionId': 'test-session-1'
        }
    )
    print('Agent response:', response.json())

test_agent('agent_abc123')

Expected Response:

{
  "data": {
    "id": "msg_def456",
    "agentId": "agent_abc123",
    "sessionId": "test-session-1",
    "role": "assistant",
    "content": "Hello! I'd be happy to help you with your account. What specific issue are you experiencing?",
    "timestamp": "2024-12-01T12:01:00Z"
  },
  "meta": {
    "timestamp": "2024-12-01T12:01:00Z"
  }
}

Option B: Voice Testing

To test voice functionality, you'll need to configure a Twilio phone number:

Go to your Heppu dashboard
Navigate to Agents → Your Agent → Settings
Click Connect Phone Number
Follow the Twilio integration steps
Call your assigned number to test!

Learn more about voice setup →

Step 5: Set Up Webhooks (Optional)

Get notified when your agent completes calls or receives messages:

curl -X POST https://v2.heppu.ai/api/v1/webhooks \
  -H "x-api-key: $HEPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/heppu",
    "events": ["call.completed", "chat.message.received"],
    "description": "Main webhook endpoint"
  }'

async function createWebhook() {
  const response = await fetch('https://v2.heppu.ai/api/v1/webhooks', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://your-server.com/webhooks/heppu',
      events: ['call.completed', 'chat.message.received'],
      description: 'Main webhook endpoint'
    })
  });

  const data = await response.json();
  console.log('Webhook created:', data);
}

createWebhook();

webhook_data = {
    'url': 'https://your-server.com/webhooks/heppu',
    'events': ['call.completed', 'chat.message.received'],
    'description': 'Main webhook endpoint'
}

response = requests.post(
    'https://v2.heppu.ai/api/v1/webhooks',
    headers={'x-api-key': api_key},
    json=webhook_data
)

print('Webhook created:', response.json())

Learn more about webhooks →

Common Agent Configurations

Customer Support Agent

{
  "name": "Customer Support",
  "systemPrompt": "You are a helpful customer support agent. Be friendly, professional, and solve problems efficiently. If you can't help, escalate to a human agent.",
  "voice": "alloy",
  "model": "gpt-4-turbo",
  "temperature": 0.7,
  "maxCallDuration": 600
}

Appointment Scheduler

{
  "name": "Appointment Scheduler",
  "systemPrompt": "You help schedule appointments. Collect the customer's name, preferred date and time, and reason for the appointment. Confirm all details before booking.",
  "voice": "nova",
  "model": "gpt-4-turbo",
  "temperature": 0.5,
  "tools": ["calendar-booking"]
}

Lead Qualification

{
  "name": "Lead Qualifier",
  "systemPrompt": "You qualify sales leads by asking about their business needs, budget, and timeline. Be consultative and professional. Collect contact information for qualified leads.",
  "voice": "onyx",
  "model": "gpt-4-turbo",
  "temperature": 0.6,
  "tools": ["crm-integration"]
}

Next Steps

Congratulations! You've created and tested your first Heppu AI agent. Here's what to explore next:

Agent Configuration

Learn about advanced agent settings, voices, and models

Custom Tools

Extend your agent with custom integrations and APIs

Voice Calls

Set up phone numbers and handle voice calls

Webhooks

Receive real-time notifications from your agents

Troubleshooting

"Unauthorized" Error

Make sure your API key is correct and included in the request headers:

# Verify your API key is set
echo $HEPPU_API_KEY

# Use the x-api-key header (recommended)
curl -H "x-api-key: $HEPPU_API_KEY" https://v2.heppu.ai/api/v1/agents

Rate Limit Errors

If you're hitting rate limits, you may need to upgrade your plan:

{
  "error": {
    "message": "Rate limit exceeded",
    "status": 429
  }
}

Check the rate limit headers in the response:

X-RateLimit-Limit: Your rate limit
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: When the limit resets (Unix timestamp)

Agent Not Responding

If your agent isn't responding to messages:

Check that the agent status is "active"
Verify your OpenAI API key is configured (in Organization Settings)
Check the agent's system prompt is not empty
Review agent logs in the dashboard

Need Help?

Documentation: Check our API reference for detailed endpoint information
Support: Email us at support@heppu.ai

Complete Example

Here's a complete Node.js script that puts everything together:

const fetch = require('node-fetch');

const apiKey = process.env.HEPPU_API_KEY;
const baseUrl = 'https://v2.heppu.ai/api/v1';

async function main() {
  // 1. Create an agent
  console.log('Creating agent...');
  const createResponse = await fetch(`${baseUrl}/agents`, {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Quick Start Agent',
      description: 'Agent created from quick start guide',
      systemPrompt: 'You are a helpful assistant.',
      voice: 'alloy',
      model: 'gpt-4-turbo',
      temperature: 0.7
    })
  });

  const agent = await createResponse.json();
  console.log('Agent created:', agent.data.id);

  // 2. Test the agent with a message
  console.log('\nSending test message...');
  const chatResponse = await fetch(`${baseUrl}/chat/send`, {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agentId: agent.data.id,
      message: 'Hello! Can you help me?',
      sessionId: 'quickstart-session'
    })
  });

  const message = await chatResponse.json();
  console.log('Agent response:', message.data.content);

  // 3. Get agent details
  console.log('\nFetching agent details...');
  const getResponse = await fetch(`${baseUrl}/agents/${agent.data.id}`, {
    headers: { 'x-api-key': apiKey }
  });

  const details = await getResponse.json();
  console.log('Agent status:', details.data.status);
}

main().catch(console.error);

Run it:

node quickstart.js

You should see output like:

Creating agent...
Agent created: agent_abc123

Sending test message...
Agent response: Hello! I'd be happy to help you. What do you need assistance with?

Fetching agent details...
Agent status: active

That's it! You're now ready to build powerful AI agents with Heppu. Happy building!

Quick Start Guide

Agent Configuration

Custom Tools

Voice Calls

Webhooks

On this page