Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Make Your First Call

This tutorial will walk you through making your first AI-powered 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:

​
Step 1: Get Your Agent ID

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

​
From the Dashboard:

  1. Log in to your Talkover dashboard at app.talkover.ai
  2. Go to Voice Agents in the left sidebar
  3. Find your agent in the list
  4. Click on the agent to view details
  5. 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

  1. Go to Calls in your dashboard
  2. Find your call by call ID or phone number
  3. 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

IssueSolution
401 UnauthorizedCheck your environment token is correct
404 Not FoundVerify your agent ID is correct
400 Bad RequestCheck phone number format (should be +1234567890)
Call not ringingVerify the phone number is valid and can receive calls

​
Debugging Tips

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

​
Next Steps

Congratulations! You’ve successfully made your first AI-powered call. Here’s what you can explore next:
🎉 You’ve successfully made your first call with Talkover! Your AI voice agent is now ready to handle conversations.