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

# Make Calls

SigmaMind AI lets you trigger outbound phone calls either through the **Dashboard UI** or programmatically via the `POST /v1/calls` API endpoint. Your AI agent handles the conversation end-to-end — no human needed on your side.

Before you start, make sure you have:

* A configured agent
* A phone number provisioned or imported on your account
* Your SigmaMind API key (`X-API-Key`) *(for API usage)*

***

## Step 1: Get a Phone Number

You need a caller number before placing any outbound call. SigmaMind supports two options:

| Option                     | UI Path                                                | API Endpoint                    | When to Use                                                |
| -------------------------- | ------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------- |
| **Provision a new number** | Deploy → Phone Numbers → **Add Phone Number**          | `POST /v1/phone-numbers`        | Buy a SigmaMind-managed number directly                    |
| **Import your own (BYO)**  | Deploy → Phone Numbers → **Add Phone Number** → Import | `POST /v1/phone-numbers/import` | Bring a number via SIP trunking from your telecom provider |

### Via the Dashboard

1. In the left sidebar, go to **Deploy → Phone Numbers**.
2. Click **Add Phone Number**.
3. Choose to provision a new number or import an existing one via SIP trunking.
4. Once added, the number appears in your list with its active status, provider (e.g. Twilio), and assigned agent.

To configure a number after adding it, click it in the list. You'll see:

* **Phone Number Name** — a friendly label (e.g. "Debt Collection Inbound")
* **Inbound Call Setting** — assign an Inbound AI Agent and optionally an Inbound Webhook URL
* **Outbound Call Setting** — assign an Outbound AI Agent and set the outbound phone number

### Via the API

To see all numbers already on your account:

```bash theme={null}
GET https://api.sigmamind.ai/v1/phone-numbers
X-API-Key: <your-api-key>
```

Each number returned includes its assigned agent, active status, provider, and SIP configuration.

***

## Step 2: Create an Outbound Call

### Via the Dashboard

1. Go to **Deploy → Phone Numbers** and select the phone number you want to call from.
2. Scroll to the **Outbound Call Setting** section.
3. Set the **Outbound Phone Number** (the number that will appear as the caller ID).
4. Select an **Outbound AI Agent** from the dropdown — this agent will handle the call conversation.
5. Click the **Call** button at the bottom of the panel to initiate an outbound call immediately.

<Tip>
  Make sure an Outbound AI Agent is selected before clicking Call. If no agent is assigned, the call will not be initiated.
</Tip>

### Via the API

Use `POST /v1/calls` to initiate a call. The agent you pass (or the one pre-assigned to the number) will handle the conversation.

#### Required Parameters

| Parameter         | Type           | Description                                      |
| ----------------- | -------------- | ------------------------------------------------ |
| `fromPhoneNumber` | string (E.164) | Your SigmaMind number, e.g. `+14157774444`       |
| `toPhoneNumber`   | string (E.164) | The number you want to call, e.g. `+12137774445` |

#### Optional Parameters

| Parameter          | Type   | Description                                                                                          |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `agentId`          | string | Override which agent handles this call. If omitted, uses the agent assigned to the `fromPhoneNumber` |
| `dynamicVariables` | object | Key-value pairs injected into your agent's prompt at runtime, e.g. customer name, account ID         |

#### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.sigmamind.ai/v1/calls \
    -H "X-API-Key: <your-api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "fromPhoneNumber": "+14157774444",
      "toPhoneNumber": "+12137774445",
      "agentId": "agent_abc123",
      "dynamicVariables": {
        "customer_name": "John Doe",
        "plan_type": "Premium"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.sigmamind.ai/v1/calls", {
    method: "POST",
    headers: {
      "X-API-Key": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fromPhoneNumber: "+14157774444",
      toPhoneNumber: "+12137774445",
      agentId: "agent_abc123",
      dynamicVariables: {
        customer_name: "John Doe",
        plan_type: "Premium",
      },
    }),
  });

  const call = await response.json();
  console.log(call.callId); // save this for monitoring
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.sigmamind.ai/v1/calls",
      headers={
          "X-API-Key": "<your-api-key>",
          "Content-Type": "application/json",
      },
      json={
          "fromPhoneNumber": "+14157774444",
          "toPhoneNumber": "+12137774445",
          "agentId": "agent_abc123",
          "dynamicVariables": {
              "customer_name": "John Doe",
              "plan_type": "Premium",
          },
      },
  )

  call = response.json()
  print(call["callId"])  # save this for monitoring
  ```
</CodeGroup>

The response includes a `callId` — keep this to retrieve call details later.

<Tip>
  Use `dynamicVariables` to personalise each call without creating separate agents. Any variable you pass is available inside your agent's prompt at call time.
</Tip>

***

## Step 3: Run a Campaign (High-Volume Outbound)

For bulk outbound — sales blasts, reminders, surveys — use **Campaigns** instead of triggering individual calls.

### How Campaigns Work

You upload a CSV of contacts, attach an agent and a caller number, and SigmaMind dials through the list automatically with configurable concurrency.

### Via the Dashboard

1. In the left sidebar, go to **Deploy → Campaign Calls**.
2. Click **Create Campaign**.
3. Fill in the campaign details:
   * **Campaign Name** — a human-readable label for this campaign
   * **Agent** — select the AI agent that will handle all calls
   * **Phone Number** — select the caller number (must already be added under Phone Numbers)
   * **Contacts CSV** — upload a CSV file containing your contact list
   * **Concurrent Calls** — set how many calls to run in parallel
   * **Dynamic Variables** *(optional)* — add key-value pairs applied to every call in the campaign
4. To schedule the campaign for a later time, toggle **Schedule Campaign** and fill in:
   * **Date** — e.g. `2025-09-01`
   * **Time** — e.g. `09:00`
   * **Timezone** — e.g. `America/New_York`
5. Click **Launch Campaign** to start immediately, or **Save** to confirm a scheduled campaign.

Once created, your campaign appears in the Campaign Calls list with its status (`Active`, `Scheduled`, `Completed`, or `Paused`). Click a campaign to view progress, pause/resume it, or delete it.

<Note>
  Your CSV must include at minimum a column for the destination phone number in E.164 format (e.g. `+12137774445`). Additional columns can be used as dynamic variables in your agent's prompt.
</Note>

### Via the API

#### Create a Campaign

```bash theme={null}
POST https://api.sigmamind.ai/v1/campaigns
```

| Parameter           | Type    | Required | Description                                           |
| ------------------- | ------- | -------- | ----------------------------------------------------- |
| `campaignName`      | string  | ✅        | A human-readable name for this campaign               |
| `agentId`           | string  | ✅        | The agent that will handle all calls in this campaign |
| `sipPhoneNumber`    | string  | ✅        | The caller number (E.164)                             |
| `file`              | string  | ✅        | CSV file with contact list                            |
| `concurrentCalls`   | integer | —        | How many calls to run in parallel                     |
| `dynamicVariables`  | object  | —        | Variables applied to every call in the campaign       |
| `isScheduled`       | boolean | —        | Set `true` to schedule for a future time              |
| `scheduledDate`     | string  | —        | Date to launch, e.g. `2025-09-01`                     |
| `scheduledTime`     | string  | —        | Time to launch, e.g. `09:00`                          |
| `scheduledTimezone` | string  | —        | Timezone, e.g. `America/New_York`                     |

#### Example — Immediate Campaign

```bash theme={null}
curl -X POST https://api.sigmamind.ai/v1/campaigns \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignName": "September Follow-ups",
    "agentId": "agent_abc123",
    "sipPhoneNumber": "+14157774444",
    "file": "<base64-encoded-csv>",
    "concurrentCalls": 5
  }'
```

#### Example — Scheduled Campaign

```bash theme={null}
curl -X POST https://api.sigmamind.ai/v1/campaigns \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignName": "Morning Reminders",
    "agentId": "agent_abc123",
    "sipPhoneNumber": "+14157774444",
    "file": "<base64-encoded-csv>",
    "concurrentCalls": 3,
    "isScheduled": true,
    "scheduledDate": "2025-09-01",
    "scheduledTime": "09:00",
    "scheduledTimezone": "America/New_York"
  }'
```

The response includes a `campaignId` you can use to check status, update, or delete the campaign.

***

## Step 4: Monitor Calls

### Via the Dashboard

* **Conversations** — Go to **Observe → Conversations** in the sidebar to see a live and historical list of all calls. Click any call to view its transcript, duration, assigned agent, and status.
* **Analytics** — Go to **Observe → Analytics** to see aggregate metrics across all calls — total call volume, average duration, completion rates, and more.
* **Logs** — Go to **System → Logs** for a detailed technical log of call events, errors, and webhook deliveries.
* **Campaign Calls** — Go to **Deploy → Campaign Calls**, click a campaign, and view per-contact call status in real time as the campaign dials through your list.

### Via the API

#### Retrieve a Single Call

```bash theme={null}
GET https://api.sigmamind.ai/v1/calls/{callId}
X-API-Key: <your-api-key>
```

Returns: call status, direction, assigned agent, phone numbers, duration, and transcript metadata.

#### List All Calls

```bash theme={null}
GET https://api.sigmamind.ai/v1/calls?status=completed&page=1&size=20
X-API-Key: <your-api-key>
```

Filter by `status` to narrow results. Paginate with `page` and `size`.

#### Set Up Webhooks (Recommended)

Rather than polling, register a webhook to receive real-time push notifications when call events happen.

**Via the Dashboard:** Go to **System → Webhooks** (or configure the Inbound Webhook URL directly on a phone number under Deploy → Phone Numbers) to add and manage webhooks without writing any code.

**Via the API:**

```bash theme={null}
POST https://api.sigmamind.ai/v1/webhooks
```

You can scope webhooks to a specific agent using `agentId`, and list or toggle them via `GET /v1/webhooks`.

<Note>
  Webhooks are the recommended approach for production systems — they eliminate polling overhead and give you instant event delivery.
</Note>

#### Delete a Call Record

If you need to remove a call record from your account:

```bash theme={null}
DELETE https://api.sigmamind.ai/v1/calls/{callId}
X-API-Key: <your-api-key>
```

Returns `204 No Content` on success. This action cannot be undone.

***

## Quick Reference

### Dashboard Navigation

| Task                            | Where to go                                                               |
| ------------------------------- | ------------------------------------------------------------------------- |
| Add or manage phone numbers     | Deploy → Phone Numbers                                                    |
| Make a single outbound call     | Deploy → Phone Numbers → select number → Outbound Call Setting → **Call** |
| Create or manage campaigns      | Deploy → Campaign Calls                                                   |
| View call transcripts & history | Observe → Conversations                                                   |
| View call analytics             | Observe → Analytics                                                       |
| View system logs                | System → Logs                                                             |
| Manage API keys                 | Deploy → API Keys                                                         |

### API Endpoints

| Task                            | Method   | Endpoint                     |
| ------------------------------- | -------- | ---------------------------- |
| Initiate a single outbound call | `POST`   | `/v1/calls`                  |
| Get call details                | `GET`    | `/v1/calls/{callId}`         |
| List all calls                  | `GET`    | `/v1/calls`                  |
| Delete a call record            | `DELETE` | `/v1/calls/{callId}`         |
| Create a bulk campaign          | `POST`   | `/v1/campaigns`              |
| Get campaign status             | `GET`    | `/v1/campaigns/{campaignId}` |
| Register a webhook              | `POST`   | `/v1/webhooks`               |
| List phone numbers              | `GET`    | `/v1/phone-numbers`          |
| Provision a number              | `POST`   | `/v1/phone-numbers`          |
| Import a number (BYO)           | `POST`   | `/v1/phone-numbers/import`   |