Звонок голосовым агентом

Запуск одного исходящего звонка голосового агента из ваших систем. Переписка в WhatsApp для этого не нужна, достаточно номера телефона. В ответе приходит результат: взял ли человек трубку.

Звонок можно и запланировать на потом, например перезвонить клиенту завтра в 11:00. Как это сделать, смотрите ниже в разделе «Запланировать звонок».

Эндпоинты

POST https://microservice.pleep.app/api/v1/calls/make-call
GET  https://microservice.pleep.app/api/v1/calls/scheduled-calls
POST https://microservice.pleep.app/api/v1/calls/cancel-scheduled-call

Заголовки

Кому звонить

• phone: номер в международном формате, например +77001234567. Плюс, пробелы и дефисы можно оставить. Казахстанский номер можно передать и с восьмёркой: 87001234567.
• thread_id: идентификатор диалога. Номер Pleep возьмёт из диалога, а звонок продолжит этот диалог: агент увидит переписку, и расшифровка звонка попадёт туда же. Это тот же идентификатор, что в этапах лида и в получении диалогов.

Можно передать оба поля: тогда агент звонит на phone, а звонок продолжает диалог thread_id. Если у диалога нет номера, например это Instagram или Telegram, передайте phone.

Какой агент звонит

Если в аккаунте один голосовой агент, указывать его не нужно. С thread_id звонит голосовой агент того ассистента, который ведёт диалог. Если голосовых агентов несколько, передайте voice_agent_id: его можно узнать у поддержки.

Когда Pleep звонит

Только в рабочие часы из настроек аккаунта. Если рабочие часы выключены, с 9:00 до 21:00 по часовому поясу аккаунта. Вне этих часов API не звонит и отвечает 409 OUTSIDE_CALLING_HOURS с полем opens_at: с этого момента звонить можно. Запланируйте звонок на это время: передайте scheduled_at.

Pleep не звонит людям, которые отказались от звонков и сообщений, и контактам, заблокированным в мониторе.

Тело запроса

Пример

curl -X POST https://microservice.pleep.app/api/v1/calls/make-call \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{
    "phone": "+77001234567",
    "extra_prompt": "Клиент оставил заявку на сайте. Уточни, когда ему удобно подъехать."
  }'

Ответ

Запрос ждёт, пока человек возьмёт трубку или вызов закончится. Обычно это до 30 секунд, поэтому таймаут HTTP-клиента ставьте не меньше 60 секунд.

{
  "ok": true,
  "data": {
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "conversation_id": "custom_convai_5d0c9e1a",
    "call_status": "connected",
    "answered": true,
    "hangup_cause": null
  }
}

Звонок расходует минуты голосового агента так же, как звонок из сценария.

Запланировать звонок

Передайте в make-call поле scheduled_at. Pleep не звонит сразу, а сохраняет звонок и отвечает 202. В назначенное время голосовой агент звонит и продолжает тот же диалог. Если вы передали только phone, Pleep найдёт диалог по номеру или создаст новый, и в мониторе в нём появится строка «Звонок запланирован на …».

• Время нужно указывать с часовым поясом: +05:00 или Z. Время без пояса API не примет. Пустое scheduled_at API тоже не примет и ответит 422: чтобы позвонить сразу, не передавайте это поле совсем.
• Голосовой агент должен уметь звонить уже при планировании. Если к нему не подключён номер, API ответит 409 VOICE_AGENT_NOT_READY, как и на звонок сейчас.
• Часы звонков те же, что для звонка сейчас. Время вне них API отклонит с 409 OUTSIDE_CALLING_HOURS, в opens_at будет ближайшее время после scheduled_at, когда звонить можно. Время в прошлом API отклонит с 422 SCHEDULED_AT_IN_PAST.
• Перед самым звонком Pleep проверяет всё заново: не отказался ли человек от звонков, не заблокирован ли контакт, остались ли минуты, готов ли голосовой агент. Если рабочие часы с тех пор поменялись и время оказалось вне них, звонок переносится на ближайшее разрешённое время, а в moved_from остаётся исходное.
• Если человек ещё говорит с агентом (звонок начался в последние 35 минут и не закончился), звонок сдвигается на 3 минуты с причиной CALL_IN_PROGRESS, до трёх раз. moved_from при этом не меняется. После третьего раза агент звонит.
• Один звонок на лида. Если у диалога или у этого номера уже есть запланированный звонок (например, ИИ-агент запланировал его в переписке с этим номером), API ответит 409 SCHEDULED_CALL_EXISTS и вернёт его в scheduled_call. Чтобы заменить его новым, передайте "replace_scheduled": true: старый получит статус cancelled с причиной REPLACED.

ИИ-агент тоже умеет планировать звонки сам, когда клиент просит перезвонить. Для этого включите расширение «Запланированные звонки». Такие звонки попадают в тот же список с "source": "agent" и так же заменяют друг друга. Если клиент передумал, агент сам отменяет звонок (причина CANCELLED_BY_AGENT). Лиду в этапе, где ИИ выключен, агент звонок не планирует и говорит, что с клиентом свяжется менеджер.

curl -X POST https://microservice.pleep.app/api/v1/calls/make-call \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "scheduled_at": "2026-11-12T11:00:00+05:00",
    "extra_prompt": "Клиент просил перезвонить, когда освободится. Уточни, удобно ли записаться на пятницу."
  }'

Ответ 202:

{
  "ok": true,
  "data": {
    "id": "6f1c2a8e-3b0d-4c8e-9a51-2f7d0e4b9c13",
    "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
    "phone": "77001234567",
    "scheduled_at": "2026-11-12T06:00:00.000Z",
    "status": "scheduled",
    "status_reason": null,
    "moved_from": null,
    "source": "api",
    "extra_prompt": "Клиент просил перезвонить, когда освободится. Уточни, удобно ли записаться на пятницу.",
    "first_message": null,
    "call_status": null,
    "conversation_id": null,
    "created_at": "2026-11-11T09:20:00.000Z",
    "finished_at": null,
    "replaced_scheduled_call_id": null
  }
}

Время в ответах всегда в UTC.

Список запланированных звонков

GET https://microservice.pleep.app/api/v1/calls/scheduled-calls

Все звонки аккаунта, запланированные через API и ИИ-агентом, сначала новые.

curl "https://microservice.pleep.app/api/v1/calls/scheduled-calls?thread_id=thread_0765c2bd-980d-4c65-aeea-d04069646be5&status=scheduled" \
  -H "X-API-Key: pk_live_ваш_ключ"

{
  "ok": true,
  "data": {
    "scheduled_calls": [
      {
        "id": "6f1c2a8e-3b0d-4c8e-9a51-2f7d0e4b9c13",
        "thread_id": "thread_0765c2bd-980d-4c65-aeea-d04069646be5",
        "phone": "77001234567",
        "scheduled_at": "2026-11-12T06:00:00.000Z",
        "status": "scheduled",
        "status_reason": null,
        "moved_from": null,
        "source": "agent",
        "extra_prompt": "Клиент просил перезвонить завтра утром, уточнить время записи",
        "first_message": null,
        "call_status": null,
        "conversation_id": null,
        "created_at": "2026-11-11T09:20:00.000Z",
        "finished_at": null
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

Отменить запланированный звонок

POST https://microservice.pleep.app/api/v1/calls/cancel-scheduled-call

curl -X POST https://microservice.pleep.app/api/v1/calls/cancel-scheduled-call \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_ваш_ключ" \
  -d '{ "scheduled_call_id": "6f1c2a8e-3b0d-4c8e-9a51-2f7d0e4b9c13" }'

В ответе звонок со статусом cancelled и причиной CANCELLED_BY_API. Отменить можно только звонок со статусом scheduled. Для звонка, который уже набирается или сделан, API ответит 409 SCHEDULED_CALL_NOT_CANCELLABLE и вернёт его в scheduled_call.

Коды ошибок