Outbound Calling

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.

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).

Place a single call with the API endpoint:

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

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

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

For multiple recipients, use the batch endpoint:

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

{
  "recipients": [
    { "phoneNumber": "+15551234567", "metadata": { "name": "Jane",  "site": "Houston HQ" } },
    { "phoneNumber": "+15559876543", "metadata": { "name": "Mike",  "site": "Austin Campus" } }
  ],
  "callerIdName": "Acme AV Service",
  "callsPerMinute": 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.

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

{
  "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:

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:

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 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.

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.

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.*