Make Your First Call

This tutorial will walk you through making your first call using the Talkover API. You’ll learn how to get your agent ID and make a test call.

Prerequisites

Before starting this tutorial, make sure you have:

Environment Token (from Authentication Guide)
Voice Agent Created (from Quickstart Guide)
Test Phone Number ready to receive calls

Step 1: Get Your Agent ID

You need your agent ID to make calls. Here’s how to find it:

From the Dashboard:

Log in to your Talkover dashboard at app.talkover.ai
Go to Voice Agents in the left sidebar
Find your agent in the list
Click on the agent to view details
Copy the Agent ID (it looks like agent_123456)

The Agent ID is displayed in the agent details page and is required for all API calls.

Step 2: Prepare Your API Request

Now you have everything you need to make your first call:

Environment Token: talq_your_token_here
Agent ID: agent_123456
Phone Number: +1234567890

API endpoints

Individual Agent Call

POST https://app.talkover.ai/api/v1/agents/{agent_id}/call

Campaign Call

POST https://app.talkover.ai/api/v1/campaigns/{campaign_id}/call

Request headers

Authorization: Bearer talq_your_token_here
Content-Type: application/json

Request body

For Agent Calls

{
  "to": "+1234567890"
}

For Campaign calls

{
  "to": "+1234567890",
  "payload": {
    "customer_name": "John Doe",
    "customer_id": "12345"
  }
}

Step 3: Make the Call

Using cURL

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890"
  }'

Using JavaScript

const makeCall = async () => {
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+1234567890'
    })
  });
  
  const result = await response.json();
  console.log('Call initiated:', result);
};

makeCall();

Using Python

import requests

def make_call():
    url = "https://app.talkover.ai/api/v1/agents/agent_123456/call"
    headers = {
        "Authorization": "Bearer talq_your_token_here",
        "Content-Type": "application/json"
    }
    data = {
        "to": "+1234567890"
    }
    
    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    print("Call initiated:", result)

make_call()

Step 4: Understand the Response

When you successfully initiate a call, you’ll receive a response like this:

{
  "call_id": "call_789012",
  "agent_id": "agent_123456",
  "to": "+1234567890",
  "status": "initiated",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_duration": 120
}

Response fields Explained:

call_id: Unique identifier for this call
agent_id: The agent that will handle the call
to: The phone number being called
status: Current status of the call (initiated, ringing, in-progress, completed, failed)
created_at: Timestamp when the call was created
estimated_duration: Estimated call duration in seconds

Step 5: Monitor Your Call

Check Call Status in Dashboard

Go to Calls in your dashboard
Find your call by call ID or phone number
Monitor the status as it progresses:
- initiated → ringing → in-progress → completed

Call status flow

initiated → ringing → in-progress → completed
     ↓         ↓           ↓           ↓
   Call    Phone is    Agent is    Call has
  created   ringing   talking     finished

Step 6: Test Different Scenarios

Test with Different Phone Numbers

Try calling different numbers to test various scenarios:

# Test with a mobile number
curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567"}'

# Test with a landline
curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15559876543"}'

Test Error Handling

Try calling an invalid number to see error responses:

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "invalid_number"}'

Troubleshooting

Common Issues

Issue	Solution
401 Unauthorized	Check your environment token is correct
404 Not Found	Verify your agent ID is correct
400 Bad Request	Check phone number format (should be +1234567890)
Call not ringing	Verify the phone number is valid and can receive calls

Debugging Tips

Check the response for error messages
Verify your agent is properly configured
Test with a known good number first
Check your dashboard for call status updates

Next Steps

Congratulations! You’ve successfully made your first call. Here’s what you can explore next:

Design better call flows in our Call Flow Design Guide
Integrate with your application using our Integration Examples
Learn about call analytics and monitoring

🎉 You’ve successfully made your first call with Talkover! Your AI voice agent is now ready to handle conversations.

Get Started

Concepts

API Reference

Guides

Make Your First Call

Make Your First Call

Prerequisites

Step 1: Get Your Agent ID

From the Dashboard:

Step 2: Prepare Your API Request

API endpoints

Individual Agent Call

Campaign Call

Request headers

Request body

For Agent Calls

For Campaign calls

Step 3: Make the Call

Using cURL

Using JavaScript

Using Python

Step 4: Understand the Response

Response fields Explained:

Step 5: Monitor Your Call

Check Call Status in Dashboard

Call status flow

Step 6: Test Different Scenarios

Test with Different Phone Numbers

Test Error Handling

Troubleshooting

Common Issues

Debugging Tips

Next Steps

​Make Your First Call

​Prerequisites

​Step 1: Get Your Agent ID

​From the Dashboard:

​Step 2: Prepare Your API Request

​API endpoints

​Individual Agent Call

​Campaign Call

​Request headers

​Request body

​For Agent Calls

​For Campaign calls

​Step 3: Make the Call

​Using cURL

​Using JavaScript

​Using Python

​Step 4: Understand the Response

​Response fields Explained:

​Step 5: Monitor Your Call

​Check Call Status in Dashboard

​Call status flow

​Step 6: Test Different Scenarios

​Test with Different Phone Numbers

​Test Error Handling

​Troubleshooting

​Common Issues

​Debugging Tips

​Next Steps

Make Your First Call

Prerequisites

Step 1: Get Your Agent ID

From the Dashboard:

Step 2: Prepare Your API Request

API endpoints

Individual Agent Call

Campaign Call

Request headers

Request body

For Agent Calls

For Campaign calls

Step 3: Make the Call

Using cURL

Using JavaScript

Using Python

Step 4: Understand the Response

Response fields Explained:

Step 5: Monitor Your Call

Check Call Status in Dashboard

Call status flow

Step 6: Test Different Scenarios

Test with Different Phone Numbers

Test Error Handling

Troubleshooting

Common Issues

Debugging Tips

Next Steps