Running Campaigns | Smallest AI Docs

This guide walks through the complete campaign lifecycle—from setup to cleanup.

Prerequisites

Before creating a campaign, you need:

Agent ID — Create one with new_agent() or use an existing agent
Audience ID — Create one with create_audience() (see Audiences)
Phone Number ID — Retrieve available numbers with get_phone_numbers()

Getting Your Phone Number

get_phone_numbers() returns all outbound phone numbers available for campaigns:

1 from smallestai.atoms import AtomsClient
2 from smallestai.atoms.campaign import Campaign
3 
4 client = AtomsClient()
5 campaign = Campaign()
6 
7 phones = client.get_phone_numbers()
8 phone_id = phones["data"][0]["_id"]

Each phone includes provider details:

1 {
2   "status": true,
3   "data": [
4     {
5       "_id": "6963d3a8862e1cb702da7244",
6       "attributes": {
7         "provider": "plivo",
8         "phoneNumber": "+912268093560"
9       },
10       "isActive": true
11     }
12   ]
13 }

Creating a Campaign

create() creates a campaign linking your agent, audience, and phone number:

1 response = campaign.create(
2     name="January Outreach",
3     agent_id=agent_id,
4     audience_id=audience_id,
5     phone_ids=[phone_id],
6     max_retries=2,
7     retry_delay=30
8 )
9 
10 campaign_id = response["data"]["_id"]

The response includes all campaign details:

1 {
2   "status": true,
3   "data": {
4     "name": "January Outreach",
5     "agentId": "696ddd281ea16a73cb8aafbe",
6     "audienceId": "696ddd287f45bf7b27344e7c",
7     "participantsCount": 2,
8     "maxRetries": 2,
9     "retryDelay": 30,
10     "status": "draft",
11     "_id": "696ddd2a04ff172dbd8eddad"
12     // ...
13   }
14 }

Campaign Parameters

Parameter	Type	Description
`name`	string	Campaign name (required)
`agent_id`	string	Agent to handle calls (required)
`audience_id`	string	Contacts to dial (required)
`phone_ids`	list	Outbound phone number IDs (required)
`max_retries`	int	Retry attempts for failed calls (0–10, default: 3)
`retry_delay`	int	Minutes between retries (1–1440, default: 15)

Starting a Campaign

start() begins dialing contacts in the audience:

1 result = campaign.start(campaign_id)

The response confirms the campaign is processing:

1 {
2   "status": true,
3   "data": {
4     "message": "Campaign is being processed",
5     "taskId": "081a5402-3f1f-4447-a257-6dd7bc6bad60",
6     "campaignId": "696ddd2a04ff172dbd8eddad"
7   }
8 }

Monitoring Progress

get() returns the campaign status, execution history, and metrics:

1 status = campaign.get(campaign_id)
2 
3 data = status["data"]["campaign"]
4 metrics = status["data"]["metrics"]
5 
6 print(f"Status: {data['status']}")
7 print(f"Called: {metrics['contacts_called']}/{metrics['total_participants']}")
8 print(f"Connected: {metrics['contacts_connected']}")

Full status response:

1 {
2   "status": true,
3   "data": {
4     "campaign": {
5       "status": "running",
6       "executions": [
7         {
8           "executionNumber": 1,
9           "status": "completed",
10           "totalMembers": 2,
11           "processedMembers": 2
12         }
13       ]
14     },
15     // ...
16     "metrics": {
17       "total_participants": 2,
18       "contacts_called": 2,
19       "contacts_connected": 1
20     }
21   }
22 }

Cleaning Up

delete() removes the campaign and its execution history:

1 campaign.delete(campaign_id)

Running campaigns should be paused before deletion. Use pause(id) first if needed.

SDK Reference

Method	Description
`get_phone_numbers()`	List available outbound numbers (via generic client)
`create(...)`	Create a campaign
`start(id)`	Begin dialing
`get(id)`	Get status and metrics
`pause(id)`	Pause a running campaign
`delete(id)`	Remove a campaign

Tips

Why are contacts_called and contacts_connected different?

contacts_called counts dial attempts. contacts_connected counts answered calls. The difference represents voicemail, busy signals, and no-answers.

What happens when a call fails?

Failed calls enter the retry queue based on your max_retries and retry_delay settings. After all retries are exhausted, the contact is marked as failed.

Can I run multiple campaigns simultaneously?

Yes. Each campaign operates independently. Just ensure you have sufficient phone capacity for parallel dialing.

How do I change an agent mid-campaign?

Campaigns cannot change agents after creation. Create a new campaign with the desired agent and audience.