# Кампании

Кампания: цепочка сообщений, которую аккаунты Telegram отправляют контактам по расписанию.

Базовый адрес: https://api.melioralab.io/v1. Ключ передается в заголовке `Authorization: Bearer mel_live_...`.

Маршруты:

- `GET /v1/campaigns`: Список кампаний
- `GET /v1/campaigns/{id}`: Получить кампанию

## Объект Campaign

Кампания: цепочка сообщений, которую аккаунты Telegram отправляют контактам.

| Поле | Тип | Описание |
|---|---|---|
| `object` | string | Тип объекта, всегда `campaign`. |
| `id` | string (uuid) | Идентификатор кампании. |
| `workspace_id` | string (uuid) | Пространство, которому принадлежит кампания. |
| `name` | string | Название кампании. |
| `status` | string | Статус кампании. Неизвестное значение приходит как `unknown`. Значения: `draft`, `scheduled`, `active`, `paused`, `stopped`, `completed`, `archived`, `launching`, `failed`, `paused_no_credits`, `unknown`. |
| `first_message_mode` | string | Откуда берется первое сообщение. В v1 всегда `template`: из шаблона кампании. |
| `accepts_api_leads` | boolean | Принимает ли кампания контакты через API. В v1 всегда `false`. |
| `reason` | object | Почему кампания сейчас не отправляет сообщения, если это известно. |
| `reason.reason_code` | string | Код причины. Значения: `none`, `schedule_window`, `daily_limit`, `queue_pending`, `telegram_wait`, `account_unavailable`, `account_restricted`, `campaign_paused`, `subscription_inactive`, `manual_hold`, `automation_stopped`, `service_unavailable`, `unknown`. |
| `reason.reason_observed_at` | string (date-time) или null | Когда причина была зафиксирована. `null`, если неизвестно. |
| `reason.next_attempt_at` | string (date-time) или null | Когда ожидается следующая попытка. `null`, если срок неизвестен. |
| `reason.requires_customer_action` | boolean или null | Нужны ли действия в кабинете, чтобы отправка продолжилась. `null`, если неизвестно. |
| `created_at` | string (date-time) | Когда кампания создана. |
| `observed_at` | string (date-time) | Время чтения данных сервером. |

Пример:

```json
{
  "object": "campaign",
  "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "name": "Пример кампании",
  "status": "active",
  "first_message_mode": "template",
  "accepts_api_leads": false,
  "reason": {
    "reason_code": "none",
    "reason_observed_at": null,
    "next_attempt_at": null,
    "requires_customer_action": null
  },
  "created_at": "2026-10-20T08:00:00.000Z",
  "observed_at": "2026-10-27T09:15:42.000Z"
}
```

## Список кампаний

`GET /v1/campaigns`

Кампании в охвате ключа, от старых к новым по `created_at`.

Право: `campaigns:read`. Вес запроса: 2.

### Параметры

| Параметр | Где | Тип | Обязательный | Описание |
|---|---|---|---|---|
| `limit` | строка запроса | integer | нет | Сколько объектов вернуть на странице. От 1 до 100. По умолчанию `50`. |
| `cursor` | строка запроса | string | нет | Значение `next_cursor` из предыдущего ответа. Остальные фильтры должны совпадать с первым запросом. |
| `workspace_id` | строка запроса | string (uuid) | нет | Только объекты этого пространства. |
| `status` | строка запроса | string | нет | Только кампании с этим статусом. Значения: `draft`, `scheduled`, `active`, `paused`, `stopped`, `completed`, `archived`, `launching`, `failed`, `paused_no_credits`, `unknown`. |

### Ответ

Список: `object`, `data`, `has_more`, `next_cursor`. Пагинация: https://docs.melioralab.io/md/pagination.md

### Особые ошибки

- `cursor_mismatch` (400): Курсор поврежден, выдан для другого маршрута или фильтров, либо права и охват ключа изменились.
- `scope_required` (403): Ключ не имеет права на это чтение. Для текстов нужен также включенный «Текст сообщений».
- `not_found` (404): Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.
- `cursor_expired` (410): Срок курсора истек: 15 минут для списков, 30 суток для ленты событий.

Общие ошибки: https://docs.melioralab.io/md/errors.md

### Пример запроса

```bash
curl -G https://api.melioralab.io/v1/campaigns \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d workspace_id=3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43 \
  -d status=active
```

### Пример ответа

```json
{
  "object": "list",
  "data": [
    {
      "object": "campaign",
      "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
      "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "name": "Пример кампании",
      "status": "active",
      "first_message_mode": "template",
      "accepts_api_leads": false,
      "reason": {
        "reason_code": "none",
        "reason_observed_at": null,
        "next_attempt_at": null,
        "requires_customer_action": null
      },
      "created_at": "2026-10-20T08:00:00.000Z",
      "observed_at": "2026-10-27T09:15:42.000Z"
    },
    {
      "object": "campaign",
      "id": "6e3a9c15-2b7d-4f80-9a64-3c1d8e5f7b29",
      "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "name": "Повторное касание",
      "status": "paused",
      "first_message_mode": "template",
      "accepts_api_leads": false,
      "reason": {
        "reason_code": "campaign_paused",
        "reason_observed_at": "2026-10-25T16:40:00.000Z",
        "next_attempt_at": null,
        "requires_customer_action": true
      },
      "created_at": "2026-10-22T11:15:00.000Z",
      "observed_at": "2026-10-27T09:15:42.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU"
}
```

## Получить кампанию

`GET /v1/campaigns/{id}`

Одна кампания по идентификатору. Кампания вне охвата ключа дает 404, как несуществующая.

Право: `campaigns:read`. Вес запроса: 1.

### Параметры

| Параметр | Где | Тип | Обязательный | Описание |
|---|---|---|---|---|
| `id` | путь | string (uuid) | да | Идентификатор кампании. |

### Ответ

Объект `Campaign`.

### Особые ошибки

- `scope_required` (403): Ключ не имеет права на это чтение. Для текстов нужен также включенный «Текст сообщений».
- `not_found` (404): Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.

Общие ошибки: https://docs.melioralab.io/md/errors.md

### Пример запроса

```bash
curl https://api.melioralab.io/v1/campaigns/4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14 \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```

### Пример ответа

```json
{
  "object": "campaign",
  "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "name": "Пример кампании",
  "status": "active",
  "first_message_mode": "template",
  "accepts_api_leads": false,
  "reason": {
    "reason_code": "none",
    "reason_observed_at": null,
    "next_attempt_at": null,
    "requires_customer_action": null
  },
  "created_at": "2026-10-20T08:00:00.000Z",
  "observed_at": "2026-10-27T09:15:42.000Z"
}
```