Outbound Campaigns

Set up automated outbound calling campaigns to reach leads with personalized AI conversations.

Outbound Campaigns is currently in Beta. Features may change.

This guide walks you through setting up an automated outbound calling campaign to reach your leads with personalized AI conversations.

Overview

Outbound campaigns allow you to:

Upload a list of leads with contact information
Personalize each call with lead-specific context
Schedule calls within specific time windows
Track progress and results for each lead

flowchart LR
    A[Create Campaign] --> B[Add Leads]
    B --> C[Set Schedule]
    C --> D[Start Campaign]
    D --> E{Time Window?}
    E -->|Yes| F[Call Next Lead]
    E -->|No| G[Wait]
    G --> E
    F --> H{More Leads?}
    H -->|Yes| E
    H -->|No| I[Campaign Complete]

Prerequisites

Before creating a campaign, ensure you have:

An active assistant - See Assistants API
A phone number - See Phone Numbers API
A configured SIP trunk - The phone number must have a SIP trunk configured for outbound calls

Warning: The phone number used for outbound calls must have a SIP trunk configured for outbound dialing.

Quick Start

Create a Campaign

Create a campaign linked to your assistant:

curl -X POST https://api.hmsovereign.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Sales Outreach",
    "assistant_id": "YOUR_ASSISTANT_ID",
    "system_message_template": "You are calling {{name}} from {{company}}. They are interested in {{interest}}.",
    "schedule_start_time": "09:00:00",
    "schedule_end_time": "17:00:00",
    "timezone": "Europe/Amsterdam"
  }'

Add Leads

Add leads with personalization variables:

curl -X POST https://api.hmsovereign.com/api/v1/campaigns/CAMPAIGN_ID/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31612345678",
    "variables": {
      "name": "Jan de Vries",
      "company": "TechCorp",
      "interest": "enterprise AI solutions"
    }
  }'

Start the Campaign

Set the campaign status to scheduled to begin calling:

curl -X PATCH https://api.hmsovereign.com/api/v1/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "scheduled"
  }'

Monitor Progress

Check campaign progress and lead statuses:

curl https://api.hmsovereign.com/api/v1/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Personalizing Calls

System Message Template

The system_message_template is appended to your assistant's existing system messages. Use double curly brace placeholders (e.g. {{variable}}) that match keys in each lead's variables object.

Example Template:

You are calling {{name}}, the {{role}} at {{company}}.

Background:
- They expressed interest in: {{interest}}
- Previous interaction: {{last_contact}}
- Priority: {{priority}}

Your goal is to schedule a demo call.

Example Lead Variables:

{
  "name": "Maria Jansen",
  "role": "Head of Operations",
  "company": "LogiFlow BV",
  "interest": "workflow automation",
  "last_contact": "Downloaded whitepaper on Jan 5",
  "priority": "high"
}

Best Practices

Tip: Personalization Tips 1. Include the lead's name - Creates immediate rapport

Reference their company - Shows you've done your research
Mention their interest - Makes the call relevant
Keep it concise - Don't overload the assistant with context

Scheduling

Time Windows

Campaigns only make calls during the configured time window:

Field	Format	Example	Description
`schedule_start_time`	HH:MM:SS	`09:00:00`	Earliest time to start calls
`schedule_end_time`	HH:MM:SS	`17:00:00`	Latest time to start calls
`timezone`	IANA	`Europe/Amsterdam`	Timezone for the schedule

Supported Timezones

Use any valid IANA timezone:

Europe/Amsterdam
Europe/London
America/New_York
America/Los_Angeles
Asia/Tokyo
etc.

Note: Calls are processed one at a time. A new call starts only after the previous call ends.

Campaign Statuses

Status	Description	Calls Made?
`draft`	Campaign created but not active	No
`scheduled`	Campaign active, calling leads	Yes
`paused`	Temporarily stopped	No
`completed`	All leads processed	No

Status Transitions

stateDiagram-v2
    [*] --> draft
    draft --> scheduled: Start campaign
    scheduled --> paused: Pause
    paused --> scheduled: Resume
    scheduled --> completed: All leads done
    completed --> [*]

Lead Statuses

Status	Description
`pending`	Waiting to be called
`calling`	Call currently in progress
`completed`	Call finished successfully
`failed`	Call failed (connection error, etc.)
`no_answer`	No answer after attempts

Bulk Import

For large lead lists, you can add multiple leads programmatically:

const leads = [
  { phone_number: "+31612345678", variables: { name: "Jan", company: "A" } },
  { phone_number: "+31687654321", variables: { name: "Maria", company: "B" } },
  { phone_number: "+31698765432", variables: { name: "Pieter", company: "C" } },
];

for (const lead of leads) {
  await fetch(`https://api.hmsovereign.com/api/v1/campaigns/${campaignId}/leads`, {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(lead)
  });
}

**Tip: ** In the dashboard, you can upload a CSV file to bulk import leads with automatic variable mapping.

Monitoring & Results

Campaign Progress

The campaign object includes progress metrics:

{
  "total_leads": 150,
  "completed_leads": 45,
  "current_call_id": "call-uuid-123",
  "last_lead_processed_at": "2026-01-07T14:25:00.000Z"
}

Call Results

After a lead is called, you can retrieve the call details:

curl https://api.hmsovereign.com/api/v1/calls/CALL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

This includes:

Full transcript
Call duration
Call analysis (if configured on the assistant)
Recording URL (if enabled)

See Calls API for details.

Error Handling

Common Issues

Campaign not making calls

Check these conditions:

Campaign status is scheduled
Current time is within the schedule window
There are leads with pending status
Phone number has a valid SIP trunk

Leads failing immediately

Verify:

Phone numbers are in E.164 format (+31612345678)
SIP trunk is configured for outbound calls
Assistant is active and properly configured

Assistant not using lead context

Ensure:

Variable names in template match keys in lead's variables
Template uses double curly brace syntax for variables
Assistant's LLM is receiving the additional system message

API Reference

List Campaigns - GET /campaigns
Create Campaign - POST /campaigns
Update Campaign - PATCH /campaigns/:id
Add Lead - POST /campaigns/:id/leads

Assistants API - Create and configure assistants
Call Analysis Guide - Analyze campaign call results

On this page