Campaigns

A campaign dials a list of contacts with one agent. You add contacts, start it, and Vocobase works through the list at the concurrency you set — retrying the ones that do not connect and reporting progress as it goes.

How it works

Create the campaign

Pick the agent and the caller IDs to dial from. The campaign starts in draft and nothing dials yet.

Add contacts

Up to 10,000 per request. Numbers are canonicalised, so the same number written two ways becomes one contact.

Start it

Vocobase dials up to concurrency_limit contacts at once — clamped by your account’s own concurrency limit — and retries failures on your schedule, inside the dialling window.

Watch it

Poll GET /campaigns/{id}/stats, or let the ordinary session.completed webhook deliver each call’s transcript and extraction as it finishes.

Create a campaign

curl -X POST https://api.vocobase.com/api/v2/campaigns \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March renewals",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone_number_ids": ["pn_1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f"],
    "concurrency_limit": 10,
    "retry_count": 2,
    "retry_delays_minutes": [30, 240]
  }'

The response is the campaign in draft, with a campaign_id you use for everything below.

Choosing caller IDs

There are two ways to say which number the campaign dials from, and they are mutually exclusive:

	When to use it
`phone_number_ids`	Preferred. A list of imported numbers. The campaign rotates through them in order, which spreads volume across numbers.
`provider`	Legacy single-provider mode, for accounts that have not imported numbers yet.

Sending both fails unless they agree. Each number must be active, owned by you, and voice-capable — this is re-checked when the campaign starts, so a campaign whose numbers were deactivated while it sat in draft refuses to start rather than dispatching doomed calls.

tata_smartflo is rejected on campaigns. Smartflo does not support streaming voice bots on Broadcast/Dialer campaigns yet — only 1:1 click-to-call and inbound DIDs.

Retries

retry_count is how many times a contact is re-dialled after the first attempt. The wait between attempts comes from one of two fields:

cooldown_minutes — the same wait every time.
retry_delays_minutes — a per-attempt list, e.g. [30, 240] waits 30 minutes before the second attempt and 4 hours before the third. It is consulted per attempt: once the list runs out, later attempts fall back to cooldown_minutes. Max 20 entries, max 10080 minutes each.

retry_count accepts up to 20. retry_concurrency reserves slots for retries rather than capping them — it stops a backlog of retries from starving fresh contacts, and retries may still borrow the whole pool once fresh contacts are exhausted. It is inert at its default of 0.

Add contacts

curl -X POST https://api.vocobase.com/api/v2/campaigns/CAMPAIGN_ID/contacts \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "+919876543210", "name": "Asha Menon", "metadata": { "plan": "pro" } },
      { "phone": "+919812345678", "name": "Ravi Kumar" }
    ]
  }'

{
  "success": true,
  "data": {
    "added": 2,
    "duplicates": 0,
    "contacts_created": 1,
    "contacts_existing": 1,
    "campaign_reopened": false
  }
}

Five things worth knowing:

metadata reaches the bot, but not as a template variable. It arrives under campaign_context.contact_metadata, not as a pre-call variable — writing {{plan}} in the prompt renders an empty string. Prompt variables come from the campaign’s column-to-variable map, which the v2 API does not expose, so variables is empty on API-created campaigns and metadata does not appear on the session.completed payload.
Contacts are reused, not duplicated. A number already in your contact library is linked rather than re-created — that is the split between contacts_created and contacts_existing.
duplicates means already on this campaign. Those rows are skipped, not re-queued.
Adding to a finished campaign re-opens it to paused, not running. A completed campaign moves back to paused and campaign_reopened is true. Dialling has not resumed — you must call POST /campaigns/{id}/resume yourself, which is what re-validates caller IDs and provider access before any new call goes out. This is how you top up a campaign instead of creating a new one.
A stopped campaign can never be topped up. /stop is terminal and is keyed on the stop itself, not the status, so a stopped campaign that later reads completed still returns 400 INVALID_STATE.

Run it

Action	Endpoint	Allowed from
Start	`POST /campaigns/{id}/start`	`draft`
Pause	`POST /campaigns/{id}/pause`	`running`
Resume	`POST /campaigns/{id}/resume`	`paused`, `credit_exhausted`
Stop	`POST /campaigns/{id}/stop`	`running`, `paused`, `credit_exhausted`

Each returns the updated campaign. Calling one from the wrong status returns 400 INVALID_STATE. Pausing lets in-flight calls finish and dispatches no new ones. Stopping is terminal — every still-queued contact is marked skipped and the campaign cannot be resumed.

start requires enough balance for at least one 30-second call. resume only re-checks the balance when the campaign is in credit_exhausted — resuming from paused runs no credit check. Both re-validate every caller ID. If the balance runs out mid-run the campaign moves to credit_exhausted on its own; top up and resume.

Both start and resume also accept an optional body to shift concurrency mid-campaign:

{ "concurrency_limit": 6, "retry_concurrency": 2 }

concurrency_limit is clamped to 1–10; retry_concurrency must be between 0 and the resulting concurrency_limit. Omit the body to keep the campaign’s current values.

The dialling window

Campaigns only dial between 09:00 and 20:59 in your account’s timezone. The window is fixed — there is no per-campaign override and no exemption, including for promised callbacks. A campaign started outside the window reaches running and simply dials nothing until 09:00. Retries are rolled forward into the window when they are booked, and held again at dispatch time, so cooldown_minutes and retry_delays_minutes are a minimum wait, never an exact one — a retry due at 22:00 goes out the next morning.

Track progress

curl -X GET https://api.vocobase.com/api/v2/campaigns/CAMPAIGN_ID/stats \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "queued": 501,
    "in_progress": 8,
    "completed": 846,
    "failed": 61,
    "skipped": 4,
    "avg_duration_seconds": 74.2,
    "total_credits": 4318.5,
    "dispositions": { "completed": 712, "no_answer": 96, "busy": 24, "voicemail": 14 },
    "screener_encountered": 31,
    "callbacks_pending": 27
  }
}

The top five counters partition your contacts — they add up to total_contacts. dispositions does not: it breaks down only the calls that reached an outcome.

screener_encountered cuts across dispositions rather than partitioning them. A call can be both completed and screener-encountered, so do not add it to the disposition counts.

One contact’s history

GET /campaigns/{id}/contacts/{contactId}/journey returns every touch for a single contact, oldest first — each outbound attempt with its disposition and cost, plus any inbound call they made back. Use it to answer “what actually happened to this lead” without stitching sessions together yourself.

Callbacks

By default, calls ask the lead for a better time if they cannot talk now, and the campaign re-queues them for it. callbacks_pending in the stats is how many are waiting. Set callback_enabled: false at creation to turn this off. It is an opt-out, not an opt-in.

Campaign-wide extraction

Attach an extraction set to the campaign and its keys apply to every call the campaign makes, on top of whatever the agent already extracts:

curl -X POST https://api.vocobase.com/api/v2/campaigns/CAMPAIGN_ID/extraction-sets/SET_ID \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Rejected with 409 EXTRACTION_KEY_CLASH if a key in the set collides with one the agent already produces — two sources writing the same field would silently shadow each other.

Next steps

Pre-call Variables

Use contact metadata inside the prompt.

Webhook Payloads

Receive each call’s transcript and result.

Credits & Billing

What a campaign costs to run.

API Reference

Every campaign field and error code.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Campaigns

Campaigns

How it works

Create a campaign

Choosing caller IDs

Retries

Add contacts

Run it

The dialling window

Track progress

One contact’s history

Callbacks

Campaign-wide extraction

Next steps

Pre-call Variables

Webhook Payloads

Credits & Billing

API Reference

​Campaigns

​How it works

​Create a campaign

​Choosing caller IDs

​Retries

​Add contacts

​Run it

​The dialling window

​Track progress

​One contact’s history

​Callbacks

​Campaign-wide extraction

​Next steps

Pre-call Variables

Webhook Payloads

Credits & Billing

API Reference

Campaigns

How it works

Create a campaign

Choosing caller IDs

Retries

Add contacts

Run it

The dialling window

Track progress

One contact’s history

Callbacks

Campaign-wide extraction

Next steps