# Статусы лида и доставки

У лида четыре поля состояния. status говорит, где лид в кампании; delivery_state и automation_state говорят, что происходит с отправкой; reason объясняет, почему цепочка ждет.

## Как читать состояния

- `status`: итог участия лида в кампании. Меняется редко: написали, ответил, отписался.
- `delivery_state`: судьба ближайшего неотправленного сообщения цепочки, а если его нет, последнего отправленного.
- `automation_state`: идет ли цепочка для этого лида.
- `reason`: почему цепочка ждет и когда ожидается следующая попытка, если это известно.

Если данных недостаточно или источники противоречат друг другу, API отдает `unknown`, а не угадывает значение. Это нормальное состояние, а не ошибка.

## Статус лида

| `status` | Что означает |
|---|---|
| `new` | Лид добавлен в кампанию, сообщений еще не было. |
| `contacted` | Первое сообщение отправлено, ответа пока нет. |
| `completed` | Цепочка пройдена, ответа нет. |
| `replied` | Лид ответил. |
| `blocked` | Писать этому контакту нельзя или не стали: например, получателя не существует, он не принимает сообщения, ему уже писали или он в стоп-листе. |
| `failed` | Отправка не удалась. |
| `suspended` | Работа с лидом временно приостановлена, например пока отдыхает аккаунт отправителя. |
| `deleted` | Лид удален из кампании. |
| `opted_out` | Лид попросил больше не писать. |
| `unknown` | Статус не удалось определить. |

## Состояние доставки

| `delivery_state` | Что означает | Сейчас |
|---|---|---|
| `queued` | Сообщение в очереди на отправку. | Приходит |
| `held` | Отправка удержана, пока не будет решения в кабинете. | Приходит |
| `sent` | Отправка подтверждена, следующих сообщений не ожидается или они еще не запланированы. | Приходит |
| `unknown` | Исход неизвестен: например, попытка отправки не подтверждена или данных недостаточно. | Приходит |
| `waiting_queue` | Следующее сообщение ожидается, но еще не поставлено в очередь. | Пока не приходит |
| `failed` | Отправка окончательно не удалась, повтор не назначен. | Пока не приходит |

`unknown` не означает неудачу. Не отправляйте лиду сообщение повторно своими средствами только потому, что пришел `unknown`: сообщение могло дойти.

## Состояние цепочки

| `automation_state` | Что означает | Сейчас |
|---|---|---|
| `running` | Цепочка идет: кампания активна, отправка разрешена. Окно отправки, дневная норма и паузы Telegram лишь откладывают следующее сообщение. | Приходит |
| `paused` | Кампания на паузе, еще не запущена или остановилась из-за подписки. | Приходит |
| `held` | Цепочка удержана, пока не будет решения в кабинете. | Приходит |
| `stopped` | Цепочка остановлена: лид ответил, отписался, его остановили, либо кампания остановлена или в архиве. | Приходит |
| `unknown` | Состояние не удалось определить. | Приходит |
| `completed` | Все шаги цепочки выполнены. | Пока не приходит |

У лидов, для которых сейчас нет запланированного сообщения, например у ответивших или прошедших цепочку, `automation_state` пока часто приходит как `unknown`. Итог участия смотрите в `status`.

> **Важно.** Значения, отмеченные «Пока не приходит», есть в схеме, но в раннем доступе не выдаются: такие лиды приходят с `unknown`. Фильтр `GET /v1/leads?delivery_state=failed` или `waiting_queue` сейчас возвращает пустой список. Когда значения начнут приходить, мы сообщим в [журнале изменений](https://docs.melioralab.io/changelog/).

## Причина ожидания

Объект `reason` есть у лида и у кампании:

```json
{
  "reason_code": "telegram_wait",
  "reason_observed_at": "2026-10-27T08:41:07.000Z",
  "next_attempt_at": "2026-10-27T09:26:00.000Z",
  "requires_customer_action": false
}
```

| `reason_code` | Что означает | Сейчас |
|---|---|---|
| `none` | Цепочка ничего не ждет. | Приходит |
| `daily_limit` | Аккаунт отправителя исчерпал дневную норму. | Приходит |
| `queue_pending` | Сообщение ждет своей очереди на отправку. | Приходит |
| `telegram_wait` | Telegram попросил аккаунт подождать перед следующей отправкой. | Приходит |
| `account_unavailable` | Аккаунт отправителя недоступен. | Приходит |
| `account_restricted` | Telegram ограничил аккаунт отправителя. | Приходит |
| `campaign_paused` | Кампания на паузе или еще не запущена. | Приходит |
| `subscription_inactive` | Подписка не действует или закончились кредиты. | Приходит |
| `manual_hold` | Отправка удержана до решения в кабинете. | Приходит |
| `automation_stopped` | Цепочка остановлена. | Приходит |
| `unknown` | Причина неизвестна. | Приходит |
| `schedule_window` | Ждет окна отправки по расписанию кампании. | Пока не приходит |
| `service_unavailable` | Причину сейчас не удалось прочитать. | Пока не приходит |

- `next_attempt_at` заполнен, только если срок известен. Иначе `null`.
- `requires_customer_action: true` означает, что цепочка не продолжится без действий в кабинете: например, нужно запустить кампанию или продлить подписку.
- Лимиты API (ответ 429) не влияют на `reason`: это ограничения ваших запросов, а не отправки сообщений.

## Статус кампании

| `status` | Что означает |
|---|---|
| `draft` | Черновик. |
| `scheduled` | Запуск запланирован. |
| `launching` | Кампания запускается. |
| `active` | Кампания идет. |
| `paused` | На паузе. |
| `paused_no_credits` | На паузе: закончились кредиты. |
| `stopped` | Остановлена. |
| `completed` | Завершена. |
| `archived` | В архиве. |
| `failed` | Ошибка запуска или работы. |
| `unknown` | Статус не удалось определить. |

## Времена

- `first_message_sent_at`: когда отправлено первое сообщение. Если отправка не подтверждена, поле равно `null`, даже при статусе `contacted`.
- `first_reply_at`: когда пришел первый ответ.
- `created_at`: когда лид добавлен в кампанию. Не меняется.
- Все времена приходят по UTC с миллисекундами, например `2026-10-26T07:30:00.000Z`.
- `observed_at`: когда сервер прочитал данные для этого ответа. Это не время последнего изменения лида.