> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Make your first AI phone call in 5 minutes

# Quick Start Guide

This guide will walk you through making your first AI-powered phone call with Ringyo AI.

## Prerequisites

Before you begin, you'll need:

* A Ringyo account ([Sign up](https://ringyo.vercel.app/sign-up))
* A Pro or Agency plan for API access
* Your API key (available in Dashboard → Developers)

## Step 1: Get Your API Key

<Steps>
  <Step title="Open the Developer Section">
    Navigate to your [Dashboard](https://ringyo.vercel.app/dashboard) and click on **Developers** in the sidebar.
  </Step>

  <Step title="Create an API Key">
    Click **Create Key**, give it a name (e.g., "My First Key"), select the permissions you need, and click **Create**.
  </Step>

  <Step title="Copy Your Key">
    <Warning>
      Your API key will only be shown once. Copy it and store it securely.
    </Warning>

    The key will look like: `vb_live_ABC123xyz...`
  </Step>
</Steps>

## Step 2: Create a Voice Agent

Before making calls, you need a voice agent. You can create one in the dashboard or via API:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.ringyo.ai/v1/agents \
    -X POST \
    -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sarah - Receptionist",
      "voice_id": "sarah",
      "personality": "friendly and professional",
      "greeting": "Hello! Thanks for calling. How can I help you today?"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.ringyo.ai/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer vb_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Sarah - Receptionist',
      voice_id: 'sarah',
      personality: 'friendly and professional',
      greeting: 'Hello! Thanks for calling. How can I help you today?'
    })
  });

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

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ringyo.ai/v1/agents',
      headers={
          'Authorization': 'Bearer vb_live_YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Sarah - Receptionist',
          'voice_id': 'sarah',
          'personality': 'friendly and professional',
          'greeting': 'Hello! Thanks for calling. How can I help you today?'
      }
  )

  agent = response.json()
  print(f"Agent created: {agent['id']}")
  ```
</CodeGroup>

Save the `agent.id` from the response — you'll need it for making calls.

## Step 3: Make Your First Call

Now let's make an outbound call:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.ringyo.ai/v1/calls \
    -X POST \
    -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+1234567890",
      "agent_id": "YOUR_AGENT_ID",
      "context": {
        "customer_name": "John Smith",
        "purpose": "appointment reminder"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.ringyo.ai/v1/calls', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer vb_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+1234567890',
      agent_id: 'YOUR_AGENT_ID',
      context: {
        customer_name: 'John Smith',
        purpose: 'appointment reminder'
      }
    })
  });

  const call = await response.json();
  console.log('Call initiated:', call.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ringyo.ai/v1/calls',
      headers={
          'Authorization': 'Bearer vb_live_YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'to': '+1234567890',
          'agent_id': 'YOUR_AGENT_ID',
          'context': {
              'customer_name': 'John Smith',
              'purpose': 'appointment reminder'
          }
      }
  )

  call = response.json()
  print(f"Call initiated: {call['id']}")
  ```
</CodeGroup>

<Check>
  Congratulations! You've just made your first AI-powered phone call.
</Check>

## Step 4: Listen for Events

Set up a webhook to receive real-time updates about your calls:

```bash theme={null}
curl https://api.ringyo.ai/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["call.completed", "call.failed"]
  }'
```

When the call completes, you'll receive a webhook like this:

```json theme={null}
{
  "event": "call.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "duration_seconds": 145,
    "outcome": "appointment_booked",
    "transcript": "...",
    "extracted_data": {
      "appointment_date": "2024-01-20",
      "appointment_time": "14:00"
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available endpoints and parameters.
  </Card>

  <Card title="n8n Integration" icon="plug" href="/integrations/n8n">
    Connect Ringyo to n8n for powerful automations.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Learn about all webhook events and payloads.
  </Card>

  <Card title="Voice Agents" icon="robot" href="/concepts/agents">
    Deep dive into agent configuration options.
  </Card>
</CardGroup>