Copy page

Guides

Creating Outbound Campaigns

Outbound campaigns let your AI agents automatically dial a list of contacts. The agent handles each conversation, and Neuratel tracks every outcome. This guide walks through the full workflow: creating a campaign, uploading contacts, launching, and monitoring results.

How Campaigns Work

1. Create a campaign — link an agent, a caller ID number, and retry settings
2. Create a call list — upload a CSV of contacts
3. Start the campaign — Neuratel begins dialing contacts
4. Monitor progress — track outcomes, listen to recordings, review transcripts

Step 1 — Create a Campaign

Code
curl -X POST https://api.neuratel.ai/v1/campaigns \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "April Follow-Up",
    "agent_id": "agent_xyz789",
    "phone_number_id": "num_abc123",
    "max_concurrent_calls": 5,
    "retry_attempts": 2,
    "retry_delay_seconds": 3600
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

campaign = client.post("/v1/campaigns", json={
    "name": "April Follow-Up",
    "agent_id": "agent_xyz789",
    "phone_number_id": "num_abc123",
    "max_concurrent_calls": 5,
    "retry_attempts": 2,
    "retry_delay_seconds": 3600,
}).json()

campaign_id = campaign["id"]

Code
const response = await fetch("https://api.neuratel.ai/v1/campaigns", {
  method: "POST",
  headers: {
    Authorization: "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "April Follow-Up",
    agent_id: "agent_xyz789",
    phone_number_id: "num_abc123",
    max_concurrent_calls: 5,
    retry_attempts: 2,
    retry_delay_seconds: 3600,
  }),
});
const campaign = await response.json();

Response:

Code
{
  "id": "camp_def456",
  "name": "April Follow-Up",
  "status": "draft",
  "agent_id": "agent_xyz789",
  "phone_number_id": "num_abc123",
  "created_at": "2025-04-07T09:00:00Z"
}

Step 2 — Upload Contacts

CSV Format

The CSV must include a phone_number column. All other columns become template variables available in the agent's system prompt.

Code
phone_number,contact_name,company,appointment_date
+12125550101,Sarah Chen,Acme Corp,April 15
+13105550182,James Okafor,Bright Labs,April 16
+17185550199,Layla Hassan,Nova Health,April 17

Limits:

• Maximum 10,000 contacts per CSV upload
• Maximum file size: 10 MB
• Phone numbers must be E.164 format (+ country code, no spaces or dashes)

Upload the CSV

Code
curl -X POST https://api.neuratel.ai/v1/campaigns/camp_def456/contacts/import \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -F "[email protected]"

Code
with open("contacts.csv", "rb") as f:
    result = client.post(
        f"/v1/campaigns/{campaign_id}/contacts/import",
        files={"file": ("contacts.csv", f, "text/csv")},
    ).json()
print(result["imported"])  # 3

Code
const formData = new FormData();
formData.append("file", csvBlob, "contacts.csv");

const response = await fetch(
  `https://api.neuratel.ai/v1/campaigns/${campaignId}/contacts/import`,
  {
    method: "POST",
    headers: { Authorization: "Bearer nk_live_your_api_key" },
    body: formData,
  }
);
const result = await response.json();

Response:

Code
{
  "imported": 3,
  "skipped": 0,
  "errors": []
}

Step 3 — Dynamic Variables in the Agent Prompt

CSV columns are injected into the agent's system prompt as {{column_name}} variables. Neuratel substitutes the actual values per contact before each call.

Example system prompt:

Code
You are calling {{contact_name}} at {{company}} to confirm their appointment on {{appointment_date}}.
Greet them by name and verify they received the reminder email.

For the first row, the agent receives:

Code
You are calling Sarah Chen at Acme Corp to confirm their appointment on April 15.

Step 4 — Start the Campaign

Code
curl -X POST https://api.neuratel.ai/v1/campaigns/camp_def456/start \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
client.post(f"/v1/campaigns/{campaign_id}/start")

Code
await fetch(`https://api.neuratel.ai/v1/campaigns/${campaignId}/start`, {
  method: "POST",
  headers: { Authorization: "Bearer nk_live_your_api_key" },
});

Status transitions: draft → running.

Campaign Controls

Pause

Stops dialing new contacts. In-progress calls run to completion.

Code
curl -X POST https://api.neuratel.ai/v1/campaigns/camp_def456/pause \
  -H "Authorization: Bearer nk_live_your_api_key"

Resume

Continues dialing from where the campaign left off.

Code
curl -X POST https://api.neuratel.ai/v1/campaigns/camp_def456/resume \
  -H "Authorization: Bearer nk_live_your_api_key"

Stop

Permanently terminates the campaign. Create a new campaign if you need to restart.

Code
curl -X POST https://api.neuratel.ai/v1/campaigns/camp_def456/stop \
  -H "Authorization: Bearer nk_live_your_api_key"

Monitor Progress

Campaign Stats

Code
curl https://api.neuratel.ai/v1/campaigns/camp_def456/stats \
  -H "Authorization: Bearer nk_live_your_api_key"

Response:

Code
{
  "campaign_id": "camp_def456",
  "status": "running",
  "total_contacts": 3,
  "dialed": 2,
  "answered": 1,
  "completed": 1,
  "no_answer": 1,
  "failed": 0,
  "pending": 1,
  "average_duration_seconds": 142
}

Individual Call Results

Code
curl https://api.neuratel.ai/v1/campaigns/camp_def456/calls \
  -H "Authorization: Bearer nk_live_your_api_key"

Response:

Code
{
  "items": [
    {
      "call_id": "call_111",
      "contact": { "phone_number": "+12125550101", "contact_name": "Sarah Chen" },
      "status": "completed",
      "duration_seconds": 142,
      "outcome": "completed",
      "started_at": "2025-04-07T09:05:00Z"
    }
  ]
}

Status and Outcome Reference

Campaign status:

Status	Meaning
draft	Created, not yet started
running	Actively dialing
paused	Suspended, resumable
completed	All contacts processed
stopped	Manually terminated

Call outcomes:

Outcome	Meaning
completed	Answered and conversation finished
no_answer	Ring timeout, no pickup
voicemail	Answering machine detected
busy	Line busy
failed	Call could not be placed

Best Practices

• Validate phone numbers before uploading — invalid numbers burn credits without connecting
• Start max_concurrent_calls conservatively — try 5, then scale up after reviewing quality
• Enable retry logic — set retry_attempts: 2 with a 3600-second (60-minute) delay to recover missed contacts
• Pilot with a small list — upload 10 contacts first, review transcripts, then scale
• Mind time zones — schedule campaigns during the contact's local business hours

API Reference

Endpoint	Method	Description
/v1/campaigns	GET	List campaigns
/v1/campaigns	POST	Create campaign
/v1/campaigns/{id}	GET	Get campaign details
/v1/campaigns/{id}/contacts/import	POST	Upload contacts CSV
/v1/campaigns/{id}/start	POST	Start campaign
/v1/campaigns/{id}/pause	POST	Pause campaign
/v1/campaigns/{id}/resume	POST	Resume campaign
/v1/campaigns/{id}/stop	POST	Stop campaign
/v1/campaigns/{id}/stats	GET	Progress stats
/v1/campaigns/{id}/calls	GET	Individual call results

Next Steps

• Setting Up Phone Numbers — assign a caller ID number
• Post-Call Analysis — automatically evaluate call outcomes
• Production Checklist — verify your setup before go-live