Skip to main content

​
Making Your First Call

The simplest way to make a call is with a task: 
curl -X POST https://api.topcalls.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "from_number": "+18005551234",
    "task": "You are calling to confirm John's dental appointment tomorrow at 3 PM. Be friendly and professional.",
    "voice": "alloy"
  }'

​
Simple vs Advanced Configuration

​
Simple Mode (Task)

For straightforward calls: 
{
  "phone_number": "+14155551234",
  "task": "Call to confirm appointment...",
  "voice": "alloy"
}

​
Advanced Mode (Instructions)

For complex conversations with full control: 
{
  "phone_number": "+14155551234",
  "instructions": "You are Sarah, a senior scheduler...",
  "first_sentence": "Hi, this is Sarah from Bright Dental...",
  "voice": "alloy",
  "temperature": 0.7,
  "max_duration": 10
}

​
Required Parameters

ParameterTypeDescription
phone_numberstringDestination number (E.164 format: +14155551234)
task OR instructionsstringWhat the AI should do (one is required)

​
Optional Parameters

​
Voice & Mode

{
  "voice": "alloy",
  "mode": "realtime"
}
Check available voices via GET /v1/voices/builtin and available models via GET /v1/models.
Realtime Mode provides the lowest latency (~200-500ms) and most natural conversations. Legacy Mode gives you full control over voice selection and language/dialect settings. Check model and voice availability via the API.

​
Call Control

{
  "from_number": "+18005551234",
  "max_duration": 10,
  "first_sentence": "Hi, this is Sarah...",
  "background_audio": "office",
  "background_audio_gain": "medium"
}

​
Context & Knowledge

{
  "knowledge_base_ids": ["kb_xyz789"],
  "request_data": {
    "patient_name": "John Smith",
    "appointment_date": "2025-12-24"
  }
}

​
Webhooks

{
  "webhook_url": "https://your-app.com/webhooks/call-complete",
  "webhook_events": ["call.completed", "call.failed"]
}

​
Complete Example: Appointment Reminder

{
  "phone_number": "+14155551234",
  "from_number": "+18005551234",
  "instructions": "You are Sarah, a friendly appointment coordinator at Bright Dental. Your goal is to confirm {{patient_name}}'s appointment on {{appointment_date}} at {{appointment_time}}. Be warm, professional, and concise.",
  "first_sentence": "Hi {{patient_name}}, this is Sarah from Bright Dental. I'm calling to confirm your appointment tomorrow at {{appointment_time}}.",
  "voice": "alloy",
  "mode": "realtime",
  "temperature": 0.7,
  "max_duration": 5,
  "request_data": {
    "patient_name": "John Smith",
    "appointment_date": "2025-12-24",
    "appointment_time": "3:00 PM"
  },
  "webhook_url": "https://your-app.com/webhooks/call-complete"
}

​
Response

{
  "call_id": "564d4fd4-03bc-400a-abe0-05540fbeff88",
  "status": "queued"
}

​
Checking Call Status

Use the call_id to check status: 
curl https://api.topcalls.ai/v1/calls/564d4fd4-03bc-400a-abe0-05540fbeff88 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Call Statuses

StatusDescription
queuedCall created, waiting to be dispatched
in_progressCall is active
completedCall finished successfully
failedCall failed (busy, no answer, error)
cancelledCall was cancelled

​
Call Ending Behavior

The AI agent can end calls gracefully when the conversation is complete. This happens automatically when:
  • The user says goodbye or thanks you
  • All questions have been answered
  • The user explicitly asks to end the call
  • The conversation naturally concludes
The AI will speak a contextual farewell message before hanging up.
You can influence this behavior in your instructions: “Always confirm the next steps before ending the call” or “Ask if there’s anything else before saying goodbye.”

​
Common Patterns

​
Pattern 1: Simple Reminder

{
  "phone_number": "+14155551234",
  "task": "Remind the user about their appointment tomorrow at 3 PM. Be brief and friendly.",
  "voice": "alloy"
}

​
Pattern 2: Multi-Language Call

{
  "phone_number": "+14155551234",
  "instructions": "Habla solo en español. Eres un asistente de servicio al cliente...",
  "mode": "legacy",
  "stt_language": "es-ES",
  "voice": "your-spanish-voice-id"
}

​
Error Handling

​
Invalid Phone Number

{
  "status": 400,
  "title": "Invalid request body",
  "errors": [
    {
      "path": "phone_number",
      "message": "Phone number must be in E.164 format (e.g., +14155551234)"
    }
  ]
}

​
Insufficient Quota

{
  "status": 402,
  "title": "Insufficient Quota",
  "detail": "You need 5 minutes but have 3.5 remaining"
}

​
Best Practices

​
Do This

  • Validate phone numbers: Use E.164 format (+14155551234)
  • Set first_sentence: Control how the call starts
  • Use request_data: Personalize with variables
  • Configure webhooks: Get notified when calls complete
  • Test first: Try with your own number before production

​
Avoid This

  • Invalid formats: Always use E.164 format
  • Missing instructions: Provide clear task or instructions
  • Too long: Keep instructions focused (200-500 words)
  • Ignore errors: Handle API errors gracefully

​
Next Steps

Function Calling

Give your AI tools to interact with your systems.

Webhooks

Receive real-time notifications when calls complete.