# Zapini API — Automations

**Version:** 1.2.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**.

---

## Automation Control

Manage AI automation for conversations. When automation is active, manual messages are blocked until you take over the chat.

**Base URL:** `/api/v1/chat`

### Important: Automation Behavior

- When automation is **active**, manual messages are blocked to prevent conflicts with AI responses.
- Use **pause** to take over the chat and send messages manually.
- Use **resume** to let the AI handle the conversation again.
- **IMPORTANT**: To resume automation, you must first **archive** the conversation.

> **Security: Archive Required to Resume**
>
> Automation can only be resumed after archiving the conversation. This ensures the manual service session is properly closed before returning control to AI. When resuming, the conversation will be automatically unarchived.

---

### POST /chat/conversations/{uuid}/pause-automation

Pauses automation for a conversation, allowing manual messages.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| reason | string | No | Optional reason for pausing automation |

**Example Request:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/pause-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Manual takeover for VIP client"}'
```

**Response:**

```json
{
  "success": true,
  "message": "Automation paused successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": true,
    "paused_at": "2025-12-20T14:30:00Z",
    "paused_by": "John Doe",
    "reason": "Manual takeover for VIP client"
  }
}
```

**Error Responses:**

| Code | Error | Description |
|------|-------|-------------|
| 400 | NO_ACTIVE_AUTOMATION | Conversation has no active automation |
| 400 | AUTOMATION_ALREADY_PAUSED | Automation is already paused |
| 404 | NOT_FOUND | Conversation not found |

---

### POST /chat/conversations/{uuid}/resume-automation

Resumes automation for a conversation, letting AI handle responses.

> **Note:** The conversation must be archived before resuming automation.

**Example Request:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/resume-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

**Response:**

```json
{
  "success": true,
  "message": "Automation resumed successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": false,
    "resumed_at": "2025-12-20T15:00:00Z"
  }
}
```

**Error Responses:**

| Code | Error | Description |
|------|-------|-------------|
| 400 | NO_ACTIVE_AUTOMATION | Conversation has no active automation |
| 400 | AUTOMATION_NOT_PAUSED | Automation is not currently paused |
| 404 | NOT_FOUND | Conversation not found |

---

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