Campaigns

​

Lifecycle

​

Create a campaign

with open("contacts.csv", "rb") as f:
    campaign = client.campaigns.create(
        name="Q4 follow-ups",
        agent_id="<agent uuid>",
        phone_number_id="<phone number uuid>",
        contacts=f,
        max_concurrent_calls=5,
        retries_per_contact=1,
        retry_delay_seconds=300,
        scheduled_at="2026-05-10T18:00:00Z",  # optional, RFC3339
    )

​

CSV format

• First row must be headers; phone_number column is required.
• Other columns become the contact’s custom_fields (passed to the agent as variables for templating).

phone_number,first_name,order_id
+14155550100,Sam,A-12001
+14155550101,Robin,A-12002

​

Concurrent budget

sum of running campaigns’ max_concurrent_calls + this campaign’s max_concurrent_calls ≤ account concurrent_max

​

State transitions

​

Live metrics (SSE)

• 2-second data: {snapshot}\n\n ticks while the campaign runs.
• 15-second : heartbeat comments to keep proxies from idle-timing out.
• Closes with event: end when the campaign reaches a terminal status.

for event in client.campaigns.stream_events(campaign_id):
    print(event)

​

Contact pagination