Getting Started with Vox Stack

Build your first AI voice agent in 5 minutes

Prerequisites

  • Vox Stack account (sign up)
  • API key from your dashboard
  • Basic knowledge of REST APIs

Step 1: Create Your First Agent

An agent defines the personality and behavior of your voice AI. Create one with a custom system prompt.

curl -X POST "https://voxstack.dev/api/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service Agent",
    "system_prompt": "You are a helpful customer service agent. 
Be friendly, professional, and aim to resolve customer issues. 
Ask clarifying questions when needed.",
    "enabled": true
  }'

Save the id from the response - you'll need it for the next step.

Step 2: Create a Call Task

A task represents a call you want to make. It includes the phone number, agent to use, and any context data.

curl -X POST "https://voxstack.dev/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "name": "Follow-up Call",
    "to_number": "+1234567890",
    "context_data": {
      "customer_name": "John Doe",
      "order_id": "12345",
      "reason": "Follow up on recent purchase"
    }
  }'

The context_data will be available to your agent during the conversation.

Step 3: Execute the Task

Execute the task to initiate the phone call. Your agent will call the number and start the conversation.

curl -X POST "https://voxstack.dev/api/v1/tasks/YOUR_TASK_ID/execute" \
  -H "Authorization: Bearer YOUR_API_KEY"

The call will be initiated immediately. You'll receive a call_id in the response.

Step 4: Monitor the Call

Check the call status and retrieve the transcript once it's completed.

# Get call details
curl -X GET "https://voxstack.dev/api/v1/calls/YOUR_CALL_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get transcript (after call completes)
curl -X GET "https://voxstack.dev/api/v1/calls/YOUR_CALL_ID/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get call report
curl -X GET "https://voxstack.dev/api/v1/calls/YOUR_CALL_ID/report" \
  -H "Authorization: Bearer YOUR_API_KEY"

Next Steps

Complete Example (JavaScript)

const API_KEY = 'your-api-key';
const BASE_URL = 'https://voxstack.dev/api/v1';

async function makeCall() {
  // 1. Create agent
  const agentResponse = await fetch(`${BASE_URL}/agents`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Customer Service Agent',
      system_prompt: 'You are a helpful customer service agent.',
      enabled: true
    })
  });
  const agent = await agentResponse.json();
  const agentId = agent.data.agent.id;

  // 2. Create task
  const taskResponse = await fetch(`${BASE_URL}/tasks`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agent_id: agentId,
      name: 'Follow-up Call',
      to_number: '+1234567890',
      context_data: {
        customer_name: 'John Doe'
      }
    })
  });
  const task = await taskResponse.json();
  const taskId = task.data.task.id;

  // 3. Execute task
  const executeResponse = await fetch(
    `${BASE_URL}/tasks/${taskId}/execute`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  const call = await executeResponse.json();
  const callId = call.data.call.id;

  console.log('Call initiated:', callId);
  
  // 4. Poll for completion (or use webhooks)
  setTimeout(async () => {
    const callResponse = await fetch(
      `${BASE_URL}/calls/${callId}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );
    const callData = await callResponse.json();
    console.log('Call status:', callData.data.call.status);
  }, 30000);
}

makeCall();