# Outbound Calling

Have your AVCodex voice agent place phone calls. Single dials for one-off follow-ups, batches for a project punch list, full campaigns for service notifications across a client portfolio.

---

Outbound calling flips the voice agent. Instead of waiting for a tech or end-user to dial in, your AVCodex agent places the call, the recipient picks up, and the same voice agent (same prompt, same knowledge, same tools) runs the conversation.

> **Warning:** Outbound calling requires a Studio Pro plan or higher with voice agents enabled. You also need a phone number assigned to the agent.

## How it works

Outbound calls use SIP (Session Initiation Protocol) through LiveKit. When you trigger an outbound call:

1. AVCodex creates a voice room and dials the recipient via your SIP trunk.
2. The recipient's phone rings with your configured caller ID.
3. When they answer, your voice agent joins the call and begins the conversation.
4. The agent uses the same voice, greeting, system prompt, and tools as inbound calls.
5. The call is recorded as a chat session you can review on your Chats page.

Each call has a configurable maximum duration (default 10 minutes, up to 60 minutes).

## Inbound vs. outbound

| | Inbound | Outbound |
|---|---------|----------|
| **Who initiates** | The caller dials your number | Your AI dials the contact |
| **Common use** | Help desk, info, scheduling | Service follow-ups, reminders, campaigns |
| **Phone number** | Required (caller dials it) | Required (used as caller ID) |
| **Voice config** | Same | Same |
| **Tools and knowledge** | Same | Same |

## Single outbound call

Place a single call with the API endpoint:

```
POST /api/applications/:id/voice/outbound-call
```

```json
{
  "phoneNumber": "+15551234567",
  "callerIdName": "Acme AV Service",
  "maxDurationSeconds": 300,
  "metadata": {
    "recipientName": "Jane Smith",
    "reason": "post-commissioning-followup",
    "siteName": "Houston HQ Boardroom 4"
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `phoneNumber` | Yes | E.164 format (`+1...`). US 10-digit numbers are auto-prefixed. |
| `callerIdName` | No | Name displayed on caller ID. Defaults to "AI Assistant". |
| `maxDurationSeconds` | No | Max call length (60 to 3600). Defaults to 600 (10 min). |
| `metadata` | No | Custom key-value data attached to the call record. |

The response includes a `callId`, `roomName`, and `sipCallId` you can use for tracking.

## Batch calling

For multiple recipients, use the batch endpoint:

```
POST /api/applications/:id/voice/outbound-batch
```

```json
{
  "recipients": [
    { "phoneNumber": "+15551234567", "metadata": { "name": "Jane",  "site": "Houston HQ" } },
    { "phoneNumber": "+15559876543", "metadata": { "name": "Mike",  "site": "Austin Campus" } }
  ],
  "callerIdName": "Acme AV Service",
  "callsPerMinute": 5
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `recipients` | Yes | Array of phone numbers and optional metadata (max 1,000). |
| `callsPerMinute` | No | Rate limit for placing calls (1 to 60). Defaults to 5. |

Small batches (10 or fewer recipients) are placed immediately with a short delay between calls. Larger batches create a campaign that processes calls in a managed queue.

## Campaigns (CSV upload)

For larger outreach, upload a CSV of recipients. Useful for service-window notifications across a corporate refresh, post-install satisfaction calls after a 40-room rollout, or quarterly preventive-maintenance check-ins:

```
POST /api/applications/:id/voice/outbound-campaign
```

```json
{
  "csvContent": "phone,name,room,service_date\n+15551234567,Jane Smith,Boardroom 4,2026-05-01\n+15559876543,Mike Jones,Training Room 2,2026-05-02",
  "callerIdName": "Acme AV Service",
  "callsPerMinute": 10
}
```

### CSV format

Your CSV must include a header row with a phone number column. Accepted column names:

- `phone`
- `phonenumber`
- `phone_number`
- `number`

All other columns are attached as metadata to each call, so the agent has context about who it is calling.

**Example CSV:**

```csv
phone,name,site,room,service_date
+15551234567,Jane Smith,Houston HQ,Boardroom 4,2026-05-01
+15559876543,Mike Jones,Austin Campus,Training Room 2,2026-05-02
```

### Campaign status

Campaigns track progress through these statuses:

| Status | Meaning |
|--------|---------|
| `pending` | Created, not yet started |
| `running` | Calls are being placed |
| `paused` | Temporarily stopped |
| `completed` | All calls finished |
| `cancelled` | Manually stopped |

Each recipient is independently tracked as `pending`, `queued`, `calling`, `completed`, `failed`, or `no-answer`.

List your campaigns:

```
GET /api/applications/:id/voice/campaigns?limit=50&offset=0
```

## Phone number format

Phone numbers are normalized to E.164 before dialing:

- `(555) 123-4567` becomes `+15551234567` (US assumed for 10-digit numbers).
- `1-555-123-4567` becomes `+15551234567`.
- `+44 20 7946 0958` stays as-is (international).

Numbers must be between 10 and 15 digits. Invalid numbers are rejected before the call is placed.

## Use cases

| Use case | How it works |
|----------|--------------|
| **Post-install follow-up** | After a Crestron commissioning, the agent calls the room owner the next week to ask if everything is working as expected. |
| **PM scheduling** | Quarterly preventive-maintenance reminders. The agent calls the site contact to confirm a window for filter swaps and firmware checks. |
| **Service-ticket close-out** | After a ticket is marked resolved, the agent calls to verify the room is fully back online. |
| **RFP qualification** | New inbound RFP leads get a call. The agent asks scope questions (rooms, displays, control system, timeline) and schedules a sales call. |
| **Outage notifications** | A headend goes down. The agent calls affected room owners with the ETA and workaround. |

## Best practices

### System prompt for outbound

Add outbound-specific instructions to your system prompt:

```
When making an outbound call:
- Introduce yourself and state the reason for calling immediately.
- If you reach voicemail, leave a brief message with a callback number.
- Be respectful of the recipient's time. Keep calls concise.
- If asked, explain this is an AI-powered call from [Company Name].
```

### Rate limiting

Start with a low `callsPerMinute` (3 to 5) and increase gradually. High call volumes may be flagged by carriers.

### Metadata for context

Pass recipient-specific data in the `metadata` field. The agent can reference it during the call (recipient name, site, room, last service date, control system in place).

> **Tip:** Outbound calling pairs well with Heartbeat for scheduled proactive outreach. Configure Heartbeat to trigger outbound calls on a schedule instead of sending chat messages. Useful for monthly health-check calls across a managed-services portfolio.

## Troubleshooting

**Calls not connecting?**
- Verify voice mode is enabled and a phone number is assigned.
- Check the recipient's phone number is valid E.164 format.
- Confirm your SIP outbound trunk is configured (contact support if unsure).

**Recipient hears nothing?**
- Check the voice agent's greeting configuration.
- Verify a voice selection is set (stock or cloned voice).
- Review call records on the Chats page for errors.

**Campaign stuck in "pending"?**
- Large campaigns are processed asynchronously. Allow time for the queue to start.
- Confirm your plan supports outbound calling.

> **Note:** For inbound call setup, see the Phone Numbers guide. For voice agent configuration, see Voice Agents.

*AVCodex · Your AV expertise. Amplified by AI.*