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

# Managing VoIP Extensions in LaraCopilot

> Extensions are SIP endpoints assigned to a tenant that allow users to make and receive calls, join call queues, and access voicemail in LaraCopilot.

An **extension** is the fundamental calling identity in LaraCopilot. Each extension represents a SIP endpoint — a phone, softphone, or WebRTC client — that a user registers against to send and receive calls. Extensions are always scoped to a single tenant, and a tenant's `max_extensions` setting controls how many may be provisioned at once. Beyond basic calling, extensions can be enrolled as agents in call queues, accumulate call detail records, and optionally store voicemail.

## Key fields

| Field               | Type    | Description                                                     |
| ------------------- | ------- | --------------------------------------------------------------- |
| `tenant_id`         | integer | The tenant this extension belongs to. Required.                 |
| `extension_number`  | string  | The dialable short number (e.g. `1001`). Max 20 characters.     |
| `display_name`      | string  | Human-readable label shown in the admin UI and CDRs.            |
| `email`             | string  | Optional email address associated with the extension user.      |
| `secret`            | string  | SIP authentication password used by the registering device.     |
| `status`            | string  | Operational state of the extension (e.g. `active`, `disabled`). |
| `voicemail_enabled` | boolean | When `true`, unanswered calls are redirected to voicemail.      |

## Resource relationships

Extensions connect to several other platform resources:

* **Devices** — one extension can have multiple registered SIP devices (desk phones, softphones, etc.).
* **Queue agents** — an extension can be enrolled in one or more call queues, making it an available agent for inbound distribution.
* **CDRs** — every call leg involving this extension produces a call detail record scoped to the same tenant.
* **Active calls** — in-progress calls are tracked in real time against the extension.

<Note>
  Deleting an extension does not automatically unenroll it from call queues. Remove the extension from any queues it belongs to before deleting it to keep queue membership clean.
</Note>

## API examples

### Create an extension

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-instance/api/extensions \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": 1,
      "extension_number": "1001",
      "display_name": "Alice Smith",
      "email": "alice@acme.example.com",
      "secret": "s3cur3p@ss",
      "status": "active",
      "voicemail_enabled": true
    }'
  ```

  ```json Response (201) theme={null}
  {
    "message": "Extension created successfully.",
    "data": {
      "id": 42,
      "tenant_id": 1,
      "extension_number": "1001",
      "display_name": "Alice Smith",
      "email": "alice@acme.example.com",
      "status": "active",
      "voicemail_enabled": true,
      "created_at": "2026-04-22T10:05:00Z",
      "updated_at": "2026-04-22T10:05:00Z"
    }
  }
  ```
</CodeGroup>

### List extensions

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://your-instance/api/extensions?search=alice"
  ```

  ```json Response (200) theme={null}
  {
    "message": "Extensions fetched successfully.",
    "data": [
      {
        "id": 42,
        "tenant_id": 1,
        "extension_number": "1001",
        "display_name": "Alice Smith",
        "email": "alice@acme.example.com",
        "status": "active",
        "voicemail_enabled": true,
        "tenant": { "id": 1, "name": "Acme Corp" },
        "devices": []
      }
    ]
  }
  ```
</CodeGroup>

### Update an extension

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://your-instance/api/extensions/42 \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": 1,
      "extension_number": "1001",
      "display_name": "Alice Johnson",
      "email": "alice.johnson@acme.example.com",
      "secret": "n3wp@ssw0rd",
      "status": "active",
      "voicemail_enabled": true
    }'
  ```

  ```json Response (200) theme={null}
  {
    "message": "Extension updated successfully.",
    "data": {
      "id": 42,
      "display_name": "Alice Johnson",
      "email": "alice.johnson@acme.example.com",
      "voicemail_enabled": true
    }
  }
  ```
</CodeGroup>

<Tip>
  Enable `voicemail_enabled` on extensions that are frequently unattended — such as after-hours or overflow lines. This ensures callers always have a fallback rather than hearing a busy or no-answer tone.
</Tip>