# Zapini API — Voice & IVR

**Version:** 1.0.0
**Base URL:** `https://zapini.app/api/v1`

---

## Authentication

All endpoints require a Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Generate API tokens in your admin panel under **API Docs → Manage Tokens**.

---

## Voice & IVR API

**Base path:** `/api/v1/voice`

> **Permission Required:** Voice features require `twilio_voice_enabled` to be active on your tenant account. Contact your administrator or reseller to enable this feature.

### Call Handling Modes

| Mode | Description |
|------|-------------|
| `ai_only` | AI handles all incoming calls automatically |
| `human_only` | Calls are routed to human agents only |
| `ai_with_handoff` | AI handles first, then transfers to human on request |
| `ivr_menu` | Interactive Voice Response menu |

---

## Phone Numbers

### GET /voice/numbers

List all configured Twilio phone numbers.

```bash
curl -X GET https://zapini.app/api/v1/voice/numbers \
  -H "Authorization: Bearer {token}"
```

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5511999999999",
      "friendly_name": "Main Line",
      "status": "active",
      "connection_type": "twilio",
      "call_handling_mode": "ai_only",
      "ai_enabled": true,
      "recording_enabled": false,
      "ivr_enabled": false,
      "created_at": "2026-02-14T10:00:00Z"
    }
  ]
}
```

---

### GET /voice/numbers/{uuid}

Get details of a specific phone number.

---

### PATCH /voice/numbers/{uuid}

Update call handling settings for a phone number.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| call_handling_mode | string | No | Handling mode (ai_only, human_only, ai_with_handoff, ivr_menu) |
| ai_enabled | boolean | No | Enable AI for call handling |
| recording_enabled | boolean | No | Enable call recording |
| ai_system_prompt | string | No | AI system prompt |

---

## Calls (Voice)

### GET /voice/calls

List voice calls.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| phone_number_uuid | string | Filter by phone number |
| status | string | Filter by status (ringing, in-progress, completed, failed) |
| direction | string | Filter direction (inbound, outbound) |
| from | datetime | Start date |
| to | datetime | End date |
| per_page | integer | Items per page |

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "call-uuid",
      "sid": "CA...",
      "direction": "inbound",
      "from_number": "+15551234567",
      "to_number": "+5511999999999",
      "status": "completed",
      "duration": 125,
      "recording_url": null,
      "ai_handled": true,
      "started_at": "2026-02-14T10:00:00Z",
      "ended_at": "2026-02-14T10:02:05Z"
    }
  ]
}
```

---

### GET /voice/calls/{uuid}

Get full details of a specific voice call including transcript.

---

### POST /voice/calls/{uuid}/transfer

Transfer an active call to another agent or number.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| target | string | Yes | Target phone number or agent SIP address |

---

## IVR Menu

### GET /voice/numbers/{uuid}/ivr

Get the IVR menu configuration for a phone number.

---

### PUT /voice/numbers/{uuid}/ivr

Create or update the IVR menu.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| greeting | string | Yes | Initial greeting message |
| options | array | Yes | Array of menu options |
| options[].digit | string | Yes | Key press digit (0-9, *, #) |
| options[].label | string | Yes | Option description |
| options[].action | string | Yes | Action type (forward, ai, department, voicemail) |
| options[].target | string | No | Target for forward action |

**Example:**

```bash
curl -X PUT https://zapini.app/api/v1/voice/numbers/uuid/ivr \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Thank you for calling. Press 1 for Sales, 2 for Support.",
    "options": [
      {"digit": "1", "label": "Sales", "action": "ai", "target": null},
      {"digit": "2", "label": "Support", "action": "forward", "target": "+15559876543"}
    ]
  }'
```

---

*Generated by Zapini — https://zapini.app*