Copy page

Getting Started

Quickstart

This guide takes you from zero to a working AI voice agent in under 5 minutes. You'll create an agent, test it from your browser, make an outbound call, and check the call logs.

Prerequisites

• A Neuratel account (see Account Setup for the onboarding process)
• An API key — go to Organization → API Keys → Create Key in the dashboard

Set your API key as an environment variable:

Code
export NEURATEL_API_KEY="nk_live_your_api_key"

Step 1: Create Your First Agent

Create an agent by sending a POST request to /v1/agents. The only required field is name — everything else gets production-ready defaults. Here we customize the brain, voice, and transcriber:

Code
# cURL
curl -X POST "https://api.neuratel.ai/v1/agents" \
  -H "Authorization: Bearer $NEURATEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "brain": {
      "provider": "groq",
      "model": "meta-llama/llama-4-scout-17b-16e-instruct",
      "instructions": "You are a helpful customer support assistant for Acme Corp. Be concise and friendly. Answer questions about products, pricing, and shipping. If you do not know something, say so honestly."
    },
    "voice": {
      "provider": "cartesia",
      "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
      "model": "sonic-3"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3",
      "language": "en"
    }
  }'

Code
# Python
import os
import httpx

api_key = os.environ["NEURATEL_API_KEY"]

response = httpx.post(
    "https://api.neuratel.ai/v1/agents",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "My First Agent",
        "brain": {
            "provider": "groq",
            "model": "meta-llama/llama-4-scout-17b-16e-instruct",
            "instructions": "You are a helpful customer support assistant for Acme Corp. Be concise and friendly. Answer questions about products, pricing, and shipping. If you do not know something, say so honestly.",
        },
        "voice": {
            "provider": "cartesia",
            "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
            "model": "sonic-3",
        },
        "transcriber": {
            "provider": "deepgram",
            "model": "nova-3",
            "language": "en",
        },
    },
)

agent = response.json()
agent_id = agent["id"]
print(f"Created agent: {agent_id}")

Code
// JavaScript
const apiKey = process.env.NEURATEL_API_KEY;

const response = await fetch("https://api.neuratel.ai/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My First Agent",
    brain: {
      provider: "groq",
      model: "meta-llama/llama-4-scout-17b-16e-instruct",
      instructions:
        "You are a helpful customer support assistant for Acme Corp. Be concise and friendly. Answer questions about products, pricing, and shipping. If you do not know something, say so honestly.",
    },
    voice: {
      provider: "cartesia",
      voice_id: "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
      model: "sonic-3",
    },
    transcriber: {
      provider: "deepgram",
      model: "nova-3",
      language: "en",
    },
  }),
});

const agent = await response.json();
console.log(`Created agent: ${agent.id}`);

Response:

Code
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My First Agent",
  "status": "ready",
  "is_active": true,
  "brain": {
    "provider": "groq",
    "model": "meta-llama/llama-4-scout-17b-16e-instruct",
    "instructions": "You are a helpful customer support assistant for Acme Corp..."
  },
  "voice": {
    "provider": "cartesia",
    "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    "model": "sonic-3"
  },
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en"
  },
  "conversation": {
    "first_message": {
      "enabled": true,
      "text": "Hello! How can I help you today?"
    },
    "turn_detection": {
      "mode": "semantic_vad",
      "min_delay": 0.5,
      "max_delay": 6.0
    }
  },
  "version": 1,
  "created_at": "2026-04-07T12:00:00Z"
}

Save the id value — you'll use it in the next steps.

Step 2: Test via Browser

The fastest way to hear your agent is the built-in WebRTC test call:

1. Go to app.neuratel.ai
2. Navigate to Agents
3. Find "My First Agent" and click on it
4. Click the Test Call button (headset icon)
5. Allow microphone access when prompted
6. Start speaking — your agent will respond in real time

The test call runs entirely in the browser. No phone number needed.

Step 3: Make an Outbound Call

To call a real phone number, send a POST request to /v1/voice-sessions/outbound:

Code
# cURL
curl -X POST "https://api.neuratel.ai/v1/voice-sessions/outbound" \
  -H "Authorization: Bearer $NEURATEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "to_number": "+15551234567"
  }'

Code
# Python
response = httpx.post(
    "https://api.neuratel.ai/v1/voice-sessions/outbound",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": agent_id,
        "to_number": "+15551234567",
    },
)

call = response.json()
print(f"Call initiated: {call['call_id']}")

Code
// JavaScript
const callResponse = await fetch("https://api.neuratel.ai/v1/voice-sessions/outbound", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "550e8400-e29b-41d4-a716-446655440000",
    to_number: "+15551234567",
  }),
});

const call = await callResponse.json();
console.log(`Call initiated: ${call.call_id}`);

The to_number field expects E.164 format (country code + number, e.g. +15551234567).

Your organization must have at least one phone number assigned for the platform to select a caller ID. If you don't have a number yet, contact your account manager.

Step 4: View Call Logs

After the call ends, fetch the call log to see the transcript, duration, and outcome:

Code
# cURL
curl -X GET "https://api.neuratel.ai/v1/voice-sessions" \
  -H "Authorization: Bearer $NEURATEL_API_KEY"

Code
# Python
response = httpx.get(
    "https://api.neuratel.ai/v1/voice-sessions",
    headers={"Authorization": f"Bearer {api_key}"},
)

calls = response.json()
for call in calls["results"]:
    print(f"{call['id']} | {call['status']} | {call['duration_seconds']}s")

Code
// JavaScript
const logsResponse = await fetch("https://api.neuratel.ai/v1/voice-sessions", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const calls = await logsResponse.json();
calls.results.forEach((call) => {
  console.log(`${call.id} | ${call.status} | ${call.duration_seconds}s`);
});

Response:

Code
{
  "results": [
    {
      "id": "call_01JRK...",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "direction": "outbound",
      "duration_seconds": 47,
      "from_number": "+15559876543",
      "to_number": "+15551234567",
      "transcript": "...",
      "created_at": "2026-04-07T12:05:00Z"
    }
  ],
  "metadata": {
    "skip": 0,
    "limit": 100,
    "total": 1,
    "has_more": false,
    "count": 1
  }
}

You can also view all call details — full transcript, recording playback, sentiment analysis, and AI-powered summary — from Analytics in the dashboard.

What You Just Built

Step	What Happened
Create agent	Configured a Groq Llama-4-Scout brain with Cartesia voice and Deepgram transcriber
Browser test	Connected via WebRTC directly to your agent — no phone number required
Outbound call	Platform dialed a real phone number and ran the agent conversation
Call logs	Fetched structured call data including transcript and duration

Next Steps

Now that your first agent is working:

• Agent Configuration — deep dive into brain, voice, transcriber, conversation, tools, transfer, and analytics
• Voice Configuration — choose and fine-tune voices across ElevenLabs, Cartesia, and Phantom Speech
• Outbound Campaigns — automate calls to contact lists with scheduling and pacing
• Webhooks — receive real-time notifications for call events
• Workflows — build branching conversation logic with the visual DAG editor
• API Reference — browse all 100+ endpoints