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

У лида четыре поля состояния. 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.

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

Объект 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: когда сервер прочитал данные для этого ответа. Это не время последнего изменения лида.