Команды

Команда связывает прием запроса с результатами его обработки. Проверяйте ее после добавления лидов или остановки.

#Получение команды

GET /v1/commands/{id} возвращает HTTP 200 и объект команды. id берется из ответа 202 на добавление или стоп. Вес 1; тело и Idempotency-Key для GET не нужны.

Для kind=enroll ключу нужно leads:enroll, для kind=stop нужно leads:stop. Одного leads:read недостаточно. Проверяются кабинет и охват исходной кампании и пространства, в том числе после удаления или переноса карточки. Ключ другого кабинета команду не увидит.

curl

curl https://api.melioralab.io/v1/commands/bd465c91-d715-4987-ab61-e63a9f01c625 \
  -H "Authorization: Bearer $MELIORA_API_KEY"

#Состояния

accepted: команда сохранена, обработка еще ожидается.
running: команда обрабатывается.
done: обработка завершена. Для добавления проверьте каждый элемент: среди них могут быть отказы и удержания. Состояние не подтверждает отправку сообщения.
done_with_unknown: остановка завершена, но исход некоторых прошлых отправок неизвестен. Смотрите result.unknown_outcome_message_ids; не повторяйте отправку.
failed: обработка команды завершилась ошибкой. Сохраните команду и причины элементов для диагностики; сначала сверьте лидов, затем решайте, какие отклоненные элементы исправить и отправить отдельной операцией.

finished_at заполнен после завершения, до него null. У стопа cleanup_pending показывает незавершенную уборку. Наблюдение команды не является действием отправки и не возобновляет цепочку.

#Итоги

У добавления result.accepted и result.inserted содержат счетчики, а items содержит результаты в исходном порядке с input_index от нуля. status (accepted, existing, rejected) фиксирует итог приема. queue_state (waiting, queued, held, failed, stopped, not_required) показывает дальнейшую постановку. Их значения описаны в добавлении лидов.

У стопа items=[]. В result приходят automation_state (stopped или stopping), send_in_flight и unknown_outcome_message_ids. См. остановку лида. Команда не возвращает первый текст и не позволяет изменить уже принятые поля.

#Опрос

Опрашивайте одну команду с паузой, например 2 секунды, без параллельных циклов. При 429/503 повторяйте GET после Retry-After с разбросом; при 401/403 остановите опрос и исправьте доступ. Не повторяйте POST с новым ключом только потому, что команда еще работает.

Примеры используют функцию meliora() из лимитов и повторов, которая обрабатывает 429/503. Ограничение в 60 опросов прекращает ожидание, но не отменяет команду: сохраните ID для продолжения позже.

terminal = {"done", "done_with_unknown", "failed"}
command_id = "bd465c91-d715-4987-ab61-e63a9f01c625"
for _ in range(60):
    command = meliora(f"/commands/{command_id}")
    if command["state"] in terminal and not command["cleanup_pending"]:
        print(command)
        break
    time.sleep(2)
else:
    raise TimeoutError(f"Command still pending: {command_id}")

const terminal = new Set(['done', 'done_with_unknown', 'failed']);
const commandId = 'bd465c91-d715-4987-ab61-e63a9f01c625';
let settled = false;
for (let i = 0; i < 60; i++) {
  const command = await meliora(`/commands/${commandId}`);
  if (terminal.has(command.state) && !command.cleanup_pending) {
    console.log(command);
    settled = true;
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
if (!settled) throw new Error(`Command still pending: ${commandId}`);

После done у добавления смотрите состояния лидов и события: только подтвержденный факт отправки дает message.sent или lead.first_message_sent. После стопа ожидайте lead.stopped; его публикация может произойти позже ответа команды.