Лиды

Работа с лидом по идентификатору диалога: чтение и изменение этапа в воронке, а также включение и выключение ИИ-агента в конкретном диалоге. Используйте, чтобы держать Pleep в согласии с вашей учётной системой: переводить лид на «Продажу», когда оплата подтвердилась на вашей стороне, или выключать агента, когда в вашей карточке лида поднят флаг «не обрабатывать ИИ».

Эндпоинты

POST https://microservice.pleep.app/api/v1/leads/get-statuses
POST https://microservice.pleep.app/api/v1/leads/get-lead
POST https://microservice.pleep.app/api/v1/leads/set-status
POST https://microservice.pleep.app/api/v1/leads/set-ai

Заголовки

Лимиты запросов

Методы этапов лида допускают 60 запросов в минуту на один API-ключ. Это отдельный лимит: у остальных методов API он равен 30.

get-statuses

Возвращает воронку целиком: идентификаторы и названия этапов. Вызовите один раз, сохраните соответствие этапов у себя и дальше работайте по id.

Тело запроса

curl -X POST https://microservice.pleep.app/api/v1/leads/get-statuses \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{}'

Ответ

{
  "ok": true,
  "data": {
    "assistant_id": "6cc47669-8659-40ad-9d4d-bf914323120d",
    "statuses": [
      {
        "id": "1a2b3c4d-0000-1111-2222-333344445555",
        "name": "Новое обращение",
        "kind": "active",
        "order": 0,
        "description": null,
        "ai_enabled": true,
        "ai_transition_locked": false
      },
      {
        "id": "9c8b7a60-7777-8888-9999-000011112222",
        "name": "Продажа",
        "kind": "success",
        "order": 10,
        "description": "Оплата подтверждена",
        "ai_enabled": false,
        "ai_transition_locked": true
      }
    ]
  }
}

get-lead

Текущий этап одного диалога.

Тело запроса

curl -X POST https://microservice.pleep.app/api/v1/leads/get-lead \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{"thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5"}'

Ответ

{
  "ok": true,
  "data": {
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "assistant_id": "6cc47669-8659-40ad-9d4d-bf914323120d",
    "channel": "WABA_COEXISTENCE",
    "phone": "77051234567",
    "message_handler": "AI",
    "status": {
      "id": "7f3a1c20-1111-2222-3333-444455556666",
      "name": "Визит назначен",
      "kind": "active",
      "order": 6
    },
    "status_set_at": "2026-08-20T10:00:00.000Z",
    "status_set_by": "AI"
  }
}

set-status

Переводит лид на этап. Делает ровно то же, что перетаскивание карточки оператором: карточка двигается на всех открытых досках в реальном времени, и запускаются сценарии, привязанные к этапу.

Тело запроса

Нужно передать ровно одно из полей status_id или status_name. Если не передать ни одного, вернётся 422: отсутствие поля не считается командой «снять этап», иначе ошибка в вашем коде молча стирала бы позицию лида в воронке.

curl -X POST https://microservice.pleep.app/api/v1/leads/set-status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "status_id": "9c8b7a60-7777-8888-9999-000011112222"
  }'

Ответ

{
  "ok": true,
  "data": {
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "changed": true,
    "answered_pending_message": false,
    "status": {
      "id": "9c8b7a60-7777-8888-9999-000011112222",
      "name": "Продажа",
      "kind": "success",
      "order": 10,
      "ai_enabled": false
    }
  }
}

Если лид уже находится на этом этапе, вернётся changed: false и ничего не произойдёт: ни записи в истории, ни запуска сценариев. Повторная отправка одного и того же запроса безопасна.

Ответ на ждущее сообщение

Бывает так, что клиент уже что-то написал, пока агент до лида не допущен: например, этап запрещает агенту отвечать, пока ваша проверка заявки не завершилась. Такое сообщение сохраняется, но остаётся без ответа, и после перевода на разрешающий этап агент сам к нему не вернётся, пока клиент не напишет снова.

Передайте answer_pending_message: true, чтобы при переводе агент ответил на это сообщение. В ответе придёт answered_pending_message: true, если ждущее сообщение нашлось и агент на него отвечает, false, если отвечать было не на что.

Поле необязательное и по умолчанию выключено намеренно: перевод этапа не должен неожиданно отправлять сообщения клиентам. Массовая синхронизация этапов из вашей системы без этого флага не напишет ни одному клиенту.

Ответ не отправляется, если на новом этапе агент запрещён (ai_enabled: false), если этап снимается (status_id: null), если последним в диалоге писал не клиент, или если сообщение старше суток.

Названия-дубли

Если в воронке несколько этапов с одинаковым названием, set-status по status_name вернёт 422 STATUS_AMBIGUOUS вместо того, чтобы выбрать один наугад. В этом случае используйте status_id.

set-ai

Включает и выключает ИИ-агента в одном диалоге. Это программный эквивалент переключателя «Выключить ИИ навсегда» в карточке диалога в мониторе.

Тело запроса

ai_enabled должен быть настоящим JSON-логическим значением. Строка "false" вернёт 422, а не выключит агента: строка в JSON истинна, и молчаливое прочтение её как «включить» дало бы прямо противоположный результат. Отсутствие поля тоже вернёт 422, а не выключение по умолчанию.

curl -X POST https://microservice.pleep.app/api/v1/leads/set-ai \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "ai_enabled": false
  }'

Ответ

{
  "ok": true,
  "data": {
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "ai_enabled": false,
    "message_handler": "OPERATOR",
    "changed": true,
    "answered_pending_message": false
  }
}

Повторная отправка одного и того же запроса безопасна: при совпадении состояния вернётся changed: false, без записи в историю диалога и без повторного пробуждения агента.

Выключение держится

ai_enabled: false выключает агента в этом диалоге насовсем. Обратно его не включит ни таймер автовозврата после ответа оператора, ни правило этапа CRM, ни перевод лида на другой этап. Единственное, что включает агента обратно, это ai_enabled: true или переключатель в мониторе.

Ответ, который уже готовится

Если в момент запроса агент уже сочиняет ответ, работают две независимые защиты.

Первая: запрос обрывает генерацию на месте. Вторая, на случай если ответ всё же успел дописаться: непосредственно перед отправкой система заново перечитывает состояние диалога и выбрасывает ответ, если агент к этому моменту выключен.

Единственное, что всё же может дойти до клиента, это часть ответа, уже переданная в мессенджер до того, как ваш запрос был получен.

Включение обратно

ai_enabled: true включает агента и сразу отвечает на сообщение, которое клиент написал, пока агент молчал, если такое сообщение есть. В answered_pending_message придёт true, если агент взялся за такое сообщение, и false, если отвечать было не на что. Те же ограничения, что и у answer_pending_message в set-status: не отвечаем, если последним писал не клиент или если сообщение старше суток.

Коды ошибок