Outbound Calls

Outbound calls let your voice agent proactively reach out to customers. Use them for appointment reminders, follow-ups, lead qualification, surveys, collections, and any scenario where you need to initiate contact.

Triggering an Outbound Call via API

Make a single outbound call by sending a POST request:

curl -X POST "https://api.thinnest.ai/voice/outbound/dial" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz",
    "to_number": "+14155551234",
    "from_number": "+18005551234",
    "context": {
      "customer_name": "Jane Doe",
      "appointment_date": "March 10, 2026",
      "appointment_time": "2:00 PM"
    }
  }'

Response:

{
  "call_id": "call_abc123",
  "status": "initiating",
  "agent_id": "agent_xyz",
  "to_number": "+14155551234",
  "from_number": "+18005551234",
  "created_at": "2026-03-05T14:00:00Z"
}

Request Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	The voice agent to use for the call
`to_number`	string	Yes	Destination phone number (E.164 format)
`from_number`	string	Yes	Your caller ID number (must be verified)
`context`	object	No	Key-value data passed to the agent’s prompt
`scheduled_at`	string	No	ISO 8601 timestamp to schedule the call
`max_duration`	integer	No	Maximum call duration in seconds (default: 600)
`recording`	boolean	No	Enable call recording (default: agent setting)
`webhook_url`	string	No	URL to receive call status updates

Call Status Updates

If you provide a webhook_url, thinnestAI sends status updates as the call progresses:

{
  "call_id": "call_abc123",
  "status": "ringing",
  "timestamp": "2026-03-05T14:00:01Z"
}

Possible statuses:

Status	Description
`initiating`	Call is being set up
`ringing`	Phone is ringing
`in_progress`	Call is connected, conversation active
`completed`	Call ended normally
`no_answer`	Recipient did not answer
`busy`	Line was busy
`failed`	Call could not be completed
`voicemail`	Voicemail detected

Setting Up Caller ID

Your outbound calls need a verified caller ID — the number that appears on the recipient’s phone.

Using a Twilio Number

Any Twilio number in your account can be used as a caller ID:

Go to Settings → Phone Numbers.
Select or purchase a number.
Use that number as from_number in your API calls.

Caller ID Best Practices

Use a local number — Calls from local area codes have higher answer rates than toll-free numbers.
Register for STIR/SHAKEN — Verify your numbers to avoid “Spam Likely” labels.
Use consistent numbers — Customers who see the same number calling are more likely to answer.
Set up a voicemail — If customers call back, they should reach your agent or a greeting.

Scheduling Calls

Single Scheduled Call

Schedule a call for a specific time:

curl -X POST "https://api.thinnest.ai/voice/outbound/dial" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz",
    "to_number": "+14155551234",
    "from_number": "+18005551234",
    "scheduled_at": "2026-03-10T14:00:00-05:00",
    "context": {
      "purpose": "appointment_reminder",
      "appointment_date": "March 11, 2026"
    }
  }'

Canceling a Scheduled Call

curl -X POST "https://api.thinnest.ai/voice/outbound/hangup" \
  -H "Authorization: Bearer YOUR_API_KEY"

Checking Scheduled Calls

curl -X GET "https://api.thinnest.ai/voice/sessions?status=scheduled&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Batch Calling via Campaigns

For high-volume outbound calling, use campaigns. A campaign takes a list of contacts and calls them systematically using your voice agent.

Creating a Campaign

Go to Campaigns in the dashboard.
Click Create Campaign.
Configure the campaign:

Setting	Description
Name	A descriptive name for the campaign
Agent	The voice agent to use
From Number	Your caller ID
Contact List	Upload a CSV or connect to your CRM
Schedule	When to start calling
Calling Window	Hours during which calls are allowed (e.g., 9 AM - 6 PM)
Timezone	Respect recipient timezone
Concurrency	How many simultaneous calls (e.g., 5)
Retry Policy	How many times to retry unanswered calls

Contact List Format

Upload a CSV with the following columns:

phone_number,name,email,custom_field_1,custom_field_2
+14155551234,Jane Doe,jane@example.com,Enterprise,March 10
+14155555678,John Smith,john@example.com,Starter,March 12

The columns beyond phone_number are passed as context to your agent.

Campaign via API

curl -X POST "https://api.thinnest.ai/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminders - March",
    "agent_id": "agent_xyz",
    "from_number": "+18005551234",
    "contacts": [
      {
        "phone_number": "+14155551234",
        "context": {
          "name": "Jane Doe",
          "appointment": "March 10 at 2 PM"
        }
      },
      {
        "phone_number": "+14155555678",
        "context": {
          "name": "John Smith",
          "appointment": "March 12 at 10 AM"
        }
      }
    ],
    "settings": {
      "calling_window_start": "09:00",
      "calling_window_end": "18:00",
      "timezone": "America/New_York",
      "max_concurrent_calls": 5,
      "retry_attempts": 2,
      "retry_delay_minutes": 60
    }
  }'

Monitoring Campaign Progress

curl -X GET "https://api.thinnest.ai/campaigns/campaign_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "campaign_abc123",
  "name": "Appointment Reminders - March",
  "status": "in_progress",
  "progress": {
    "total": 150,
    "completed": 87,
    "in_progress": 5,
    "pending": 42,
    "failed": 16
  },
  "started_at": "2026-03-05T09:00:00Z"
}

Pausing and Resuming

# Pause
curl -X POST "https://api.thinnest.ai/campaigns/campaign_abc123/pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Resume
curl -X POST "https://api.thinnest.ai/campaigns/campaign_abc123/resume" \
  -H "Authorization: Bearer YOUR_API_KEY"

Handling Voicemail Detection

When an outbound call reaches voicemail, your agent can detect it and respond appropriately.

Configuration

Enable voicemail detection in your agent settings:

{
  "voicemail_detection": {
    "enabled": true,
    "action": "leave_message",
    "message": "Hi, this is Sarah from Acme Corp calling about your upcoming appointment on {appointment_date}. Please call us back at 1-800-555-1234 to confirm. Thank you!"
  }
}

Voicemail Actions

Action	Description
`leave_message`	Leave a pre-configured voicemail message
`hang_up`	Disconnect immediately
`retry_later`	Hang up and schedule a retry

Detection Accuracy

Voicemail detection works by analyzing audio patterns:

Answering machine greetings (beep detection)
Carrier voicemail messages
Ring-to-voicemail timing

Detection accuracy is typically above 90%. For critical calls, enable retry_later to catch cases where detection fails.

Outbound Call Best Practices

Compliance

Respect calling hours — Only call during appropriate hours in the recipient’s timezone. A safe window is 9 AM to 8 PM local time.
Honor Do Not Call lists — Maintain and check DNC lists before calling.
Identify yourself — Your agent should clearly state who is calling and why within the first few seconds.
Provide opt-out — Give recipients a way to opt out of future calls.
Check local regulations — Outbound calling rules vary by country and state. Consult legal counsel for your specific use case.

Performance

Start with small batches — Test with 10-20 calls before running a full campaign.
Monitor answer rates — If answer rates drop below 30%, consider changing your caller ID or calling times.
Keep calls focused — Outbound calls should have a clear purpose. Long, meandering calls reduce effectiveness.
Use context — Pre-populate your agent with customer data so the conversation is relevant and personalized.
Review recordings — Listen to a sample of calls from each campaign to identify issues.

Retry Strategy

A good retry strategy improves contact rates without being aggressive:

Attempt	Delay	Notes
1st try	—	Initial call
2nd try	1 hour	Different time of day
3rd try	24 hours	Next business day
Final try	48 hours	Last attempt

After all retries are exhausted, mark the contact as “unreachable” and consider alternative channels (SMS, email).

Next Steps

Voice Configuration — Tune your agent’s voice for outbound calls
Call Recording — Record outbound calls for quality assurance
Web Calls — Add voice calls to your website

Introduction

Getting Started

Voice Agents

Agent Capabilities

Channels

Quality & Oversight

Platform

Outbound Calls

Outbound Calls

Triggering an Outbound Call via API

Request Parameters

Call Status Updates

Setting Up Caller ID

Using a Twilio Number

Caller ID Best Practices

Scheduling Calls

Single Scheduled Call

Canceling a Scheduled Call

Checking Scheduled Calls

Batch Calling via Campaigns

Creating a Campaign

Contact List Format

Campaign via API

Monitoring Campaign Progress

Pausing and Resuming

Handling Voicemail Detection

Configuration

Voicemail Actions

Detection Accuracy

Outbound Call Best Practices

Compliance

Performance

Retry Strategy

Next Steps

​Outbound Calls

​Triggering an Outbound Call via API

​Request Parameters

​Call Status Updates

​Setting Up Caller ID

​Using a Twilio Number

​Caller ID Best Practices

​Scheduling Calls

​Single Scheduled Call

​Canceling a Scheduled Call

​Checking Scheduled Calls

​Batch Calling via Campaigns

​Creating a Campaign

​Contact List Format

​Campaign via API

​Monitoring Campaign Progress

​Pausing and Resuming

​Handling Voicemail Detection

​Configuration

​Voicemail Actions

​Detection Accuracy

​Outbound Call Best Practices

​Compliance

​Performance

​Retry Strategy

​Next Steps

Outbound Calls

Triggering an Outbound Call via API

Request Parameters

Call Status Updates

Setting Up Caller ID

Using a Twilio Number

Caller ID Best Practices

Scheduling Calls

Single Scheduled Call

Canceling a Scheduled Call

Checking Scheduled Calls

Batch Calling via Campaigns

Creating a Campaign

Contact List Format

Campaign via API

Monitoring Campaign Progress

Pausing and Resuming

Handling Voicemail Detection

Configuration

Voicemail Actions

Detection Accuracy

Outbound Call Best Practices

Compliance

Performance

Retry Strategy

Next Steps