Running Campaigns

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

Prerequisites

Before creating a campaign, you need:

• Agent ID - Create one with client.atoms.agents.create_agent() or use an existing agent
• Audience ID - Create one with the Audience helper (see Audiences)
• Phone Number ID - Retrieve available numbers with client.atoms.phone_numbers.list()

Getting Your Phone Number

client.atoms.phone_numbers.list() returns all outbound phone numbers available for campaigns:

1
from smallestai import SmallestAI
2
from smallestai.atoms.helpers import Campaign
3
4
client = SmallestAI()  # reads SMALLEST_API_KEY from the environment
5
campaign = Campaign()
6
7
phones = client.atoms.phone_numbers.list()
8
phone_id = phones.data[0].id

Each phone includes provider details. The SDK returns typed objects, so _id in the raw response is phones.data[0].id and attributes.phoneNumber is phones.data[0].attributes.phone_number:

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

Scheduling a campaign (REST)

POST /campaign also accepts an optional scheduledAt (ISO-8601, must be in the future) to defer the first dial-out. If provided, the campaign is created in scheduled status and begins automatically at the specified time.

$
curl -X POST "https://api.smallest.ai/atoms/v1/campaign" \
>
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "January Outreach",
>
    "agentId": "696ddd281ea16a73cb8aafbe",
>
    "audienceId": "696ddd287f45bf7b27344e7c",
>
    "phoneNumberIds": ["6963d3a8862e1cb702da7244"],
>
    "scheduledAt": "2026-04-24T10:00:00.000Z",
>
    "maxRetries": 3,
>
    "retryDelay": 15
>
  }'

Full request/response shape: see POST /campaign in the API reference.

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)

SDK Reference

Tips