> ## Documentation Index
> Fetch the complete documentation index at: https://kb.vinfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Launch and Manage Outbound Calling Campaigns in Neuron

> Create and monitor outbound calling campaigns with Neuron — upload contacts, set schedules, configure retry logic, and track dispositions in real time.

A campaign is how you put your voice agent to work at scale. You define a contact list, attach a voice agent (with its script and language), set a calling schedule, and Neuron handles every call — dialing, conversing, disposing, and logging — within the window you configure. This page covers how to create, monitor, and manage campaigns from both the dashboard and the API.

## What Is a Campaign?

In Neuron, a campaign is a batch of outbound calls that shares a single voice agent configuration, schedule, and contact list. Every call in the campaign runs the same script and disposition logic, and all outcomes roll up into a single campaign-level report.

Campaigns are stateful — you can pause, resume, or stop them mid-run, and Neuron tracks which contacts have been reached, which need a retry, and which are complete.

## Creating a Campaign via the Dashboard

<Steps>
  <Step title="Open Campaign Creation">
    Go to **Neuron → Campaigns** in the VInfer console and click **New Campaign**.
  </Step>

  <Step title="Name Your Campaign">
    Give the campaign a clear, identifiable name. Use a naming convention that includes the use case, language, and date — for example: `Q4 Cross-Sell — Personal Loans — hi-IN — Jan 2024`.
  </Step>

  <Step title="Select Script and Language">
    Choose the script from the dropdown (scripts you've created under **Neuron → Scripts**) and set the target language. The language set here overrides the agent's default language for this campaign run.
  </Step>

  <Step title="Set Your Calling Schedule">
    Define the calling window: start date/time, end date/time, and timezone. Neuron will only place calls within this window and will automatically stop when the end time is reached.
  </Step>

  <Step title="Upload Your Contact List">
    Upload a CSV file or paste contact data directly. Required fields: `phone`. Optional fields: `name`, and any custom variables your script references (e.g., `loan_amount`, `due_date`). Maximum 10,000 contacts per campaign.
  </Step>

  <Step title="Configure Retry Logic">
    Set `max_attempts` (how many times to retry unreached contacts) and the retry interval (minimum time between attempts for the same contact).
  </Step>

  <Step title="Launch">
    Review your configuration and click **Launch Campaign**. Neuron begins dialing immediately at the campaign start time.
  </Step>
</Steps>

## Creating a Campaign via the API

For programmatic campaign creation — useful for automated workflows, CRM-triggered campaigns, or bulk scheduling — use the `POST /v1/campaigns` endpoint:

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.vinfer.ai/v1/campaigns \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q4 Cross-Sell — Personal Loans",
      "script_id": "script_crosssell_pl_v3",
      "language": "hi-IN",
      "schedule": {
        "start_time": "2024-01-15T09:00:00+05:30",
        "end_time": "2024-01-15T18:00:00+05:30",
        "timezone": "Asia/Kolkata"
      },
      "contacts": [
        {"phone": "+919876543210", "name": "Priya Sharma", "loan_amount": 50000},
        {"phone": "+919123456789", "name": "Amit Patel", "loan_amount": 75000}
      ],
      "max_attempts": 3
    }'
  ```

  ```json Response theme={null}
  {
    "campaign_id": "cmp_8f3a2b1c9d4e",
    "name": "Q4 Cross-Sell — Personal Loans",
    "status": "scheduled",
    "script_id": "script_crosssell_pl_v3",
    "language": "hi-IN",
    "contact_count": 2,
    "schedule": {
      "start_time": "2024-01-15T09:00:00+05:30",
      "end_time": "2024-01-15T18:00:00+05:30",
      "timezone": "Asia/Kolkata"
    },
    "max_attempts": 3,
    "created_at": "2024-01-14T17:42:11+05:30"
  }
  ```
</CodeGroup>

Store the `campaign_id` from the response — you'll use it to monitor status, fetch results, and control the campaign.

## Campaign Request Parameters

<ParamField body="name" type="string" required>
  A human-readable name for the campaign. Appears in the dashboard and in all API responses.
</ParamField>

<ParamField body="script_id" type="string" required>
  The ID of the script to use for this campaign. Must be an existing script from **Neuron → Scripts**.
</ParamField>

<ParamField body="language" type="string" required>
  BCP-47 language code for this campaign. Overrides the agent's default language. See the [Languages](/neuron/languages) page for supported codes.
</ParamField>

<ParamField body="schedule" type="object" required>
  Calling window configuration. Contains `start_time`, `end_time` (ISO 8601 with timezone offset), and `timezone` (IANA timezone string, e.g., `"Asia/Kolkata"`).
</ParamField>

<ParamField body="contacts" type="array" required>
  Array of contact objects. Each object requires `phone` (E.164 format). Add any custom fields your script uses as additional keys on each contact object.
</ParamField>

<ParamField body="max_attempts" type="integer">
  Maximum number of call attempts per contact. Defaults to `1`. Set to `2` or `3` to retry unreached contacts. Retries are spaced by the configured retry interval (default: 60 minutes).
</ParamField>

## Monitoring a Running Campaign

Fetch real-time campaign status and disposition breakdown with `GET /v1/campaigns/{campaign_id}`:

```bash theme={null}
curl https://api.vinfer.ai/v1/campaigns/cmp_8f3a2b1c9d4e \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "campaign_id": "cmp_8f3a2b1c9d4e",
  "status": "running",
  "progress": {
    "total_contacts": 2000,
    "called": 1243,
    "pending": 757,
    "in_progress": 12
  },
  "dispositions": {
    "connected": 891,
    "not_reachable": 298,
    "callback_requested": 54,
    "interested": 312,
    "not_interested": 163,
    "dnc": 8
  },
  "metrics": {
    "connect_rate": 0.717,
    "avg_call_duration_seconds": 87,
    "conversion_rate": 0.251
  }
}
```

Campaign `status` values:

| Status      | Meaning                                    |
| ----------- | ------------------------------------------ |
| `scheduled` | Campaign created, waiting for start time   |
| `running`   | Actively placing calls                     |
| `paused`    | Manually paused; can be resumed            |
| `completed` | All contacts processed or end time reached |
| `stopped`   | Manually stopped; cannot be resumed        |

## Pausing, Resuming, and Stopping

<Tabs>
  <Tab title="Pause">
    ```bash theme={null}
    curl -X POST https://api.vinfer.ai/v1/campaigns/cmp_8f3a2b1c9d4e/pause \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Pausing stops new calls from being placed but allows calls already in progress to complete. All pending contacts are preserved and will be picked up on resume.
  </Tab>

  <Tab title="Resume">
    ```bash theme={null}
    curl -X POST https://api.vinfer.ai/v1/campaigns/cmp_8f3a2b1c9d4e/resume \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Resuming restarts dialing from where it left off. The campaign's original schedule end time still applies — if you resume after the scheduled end time, no new calls will be placed.
  </Tab>

  <Tab title="Stop">
    ```bash theme={null}
    curl -X POST https://api.vinfer.ai/v1/campaigns/cmp_8f3a2b1c9d4e/stop \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Stopping permanently ends the campaign. Calls in progress are allowed to complete. A stopped campaign cannot be restarted — create a new campaign with the remaining contacts if needed.
  </Tab>
</Tabs>

## Retry Logic

When a contact doesn't connect on the first attempt, Neuron's retry logic handles follow-up automatically based on your configuration:

* **`max_attempts`** — the total number of times Neuron will try each contact (including the initial call). Set `max_attempts: 3` to try each number up to 3 times.
* **Retry interval** — the minimum time Neuron waits before reattempting a contact who didn't connect. Configurable in the dashboard under campaign settings (default: 60 minutes).
* **Smart retry exclusion** — contacts with a terminal disposition (interested, not interested, DNC, paid) are never retried, regardless of `max_attempts`.

<Info>
  Retries only apply to `not_reachable` dispositions. Contacts who connected and received a terminal disposition are not re-dialed, even if `max_attempts` has not been exhausted.
</Info>

## Contact List Requirements

<AccordionGroup>
  <Accordion title="CSV Upload Format">
    Upload contacts as a CSV file with the following structure:

    ```csv theme={null}
    phone,name,loan_amount,due_date
    +919876543210,Priya Sharma,50000,2024-01-20
    +919123456789,Amit Patel,75000,2024-01-22
    ```

    * `phone` is the only required column, in E.164 format (`+91XXXXXXXXXX`)
    * Add any custom columns your script uses as additional headers
    * Maximum file size: 5 MB; maximum 10,000 contacts per campaign
  </Accordion>

  <Accordion title="API Contacts Array">
    Pass contacts directly in the API request as an array of objects. The same field rules apply — `phone` required, custom fields as additional keys. Maximum 10,000 contacts per API request.
  </Accordion>

  <Accordion title="Duplicate Handling">
    Neuron automatically deduplicates contacts within a campaign by phone number. If the same number appears multiple times in your upload, it will be called only once (or `max_attempts` times if it doesn't connect).
  </Accordion>
</AccordionGroup>

<Warning>
  You are responsible for maintaining your Do Not Call (DNC) list. VInfer automatically suppresses any number that has been flagged as DNC within your account, but it does not verify numbers against national DNC registries. Ensure your contact lists are scrubbed against applicable regulatory DNC lists before uploading. Non-compliance with telemarketing regulations is your organization's responsibility.
</Warning>

## Campaign Metrics

After a campaign completes (or while it's running), you can access the following metrics from the dashboard or via the API:

| Metric                    | Description                                                           |
| ------------------------- | --------------------------------------------------------------------- |
| **Connect Rate**          | Percentage of contacts where the call was answered                    |
| **Disposition Breakdown** | Count and percentage for each disposition tag                         |
| **Average Call Duration** | Mean call length in seconds for connected calls                       |
| **Conversion Rate**       | Percentage of connected calls with a positive outcome disposition     |
| **Retry Rate**            | Percentage of contacts that required more than one attempt to connect |
| **Escalation Rate**       | Percentage of connected calls transferred to a human agent            |

## Next Steps

* [Configure or update your voice agent](/neuron/voice-agents) before launching
* [Set up webhooks](/neuron/integrations) to receive real-time disposition events in your CRM
* [Review language options](/neuron/languages) if you're running multilingual campaigns