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

# Outbound Calls

> Trigger outbound calls to customers via API, schedule calls, and run batch calling campaigns with your voice agents.

# 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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

1. Go to **Settings → Phone Numbers**.
2. Select or purchase a number.
3. 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:

```bash theme={null}
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

```bash theme={null}
curl -X POST "https://api.thinnest.ai/voice/outbound/hangup" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Checking Scheduled Calls

```bash theme={null}
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

1. Go to **Campaigns** in the dashboard.
2. Click **Create Campaign**.
3. 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

```bash theme={null}
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

```bash theme={null}
curl -X GET "https://api.thinnest.ai/campaigns/campaign_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "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

```bash theme={null}
# 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:

```json theme={null}
{
  "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](/docs/voice/voice-configuration) — Tune your agent's voice for outbound calls
* [Call Recording](/docs/voice/call-recording) — Record outbound calls for quality assurance
* [Web Calls](/docs/voice/web-calls) — Add voice calls to your website