Agent API Документация

Аутентификация

Все запросы передают персональный API-ключ в заголовке X-Api-Key:

X-Api-Key: vfy_...

Ключ генерируется в кабинете: Настройки → API-ключ для интеграций. Полный ключ показывается один раз при генерации. При перевыпуске старый ключ мгновенно перестаёт работать.

Неверный ключ → 401 {"detail": "invalid_api_key"}.

Область действия ключа

По ключу доступны только эндпоинты этой страницы: чтение, создание и редактирование агентов + справочник моделей. Остальное API Voicyfy по ключу недоступно.

Как устроен агент (важно перед настройкой)

У агента два независимых AI-компонента, у каждого — свой скрытый базовый системный промпт (через API не редактируется):

Оркестратор — текстовый «мозг»: ведёт CRM, планирует звонки, готовит стратегию каждого звонка, анализирует результаты. Его промпт = базовый шаблон + 5 документов doc_* + additional_instructions.
Голосовой агент — говорит в живом телефонном разговоре. Его промпт в исходящих = базовый шаблон + voice_additional_instructions; во входящих на номер агента — voice_additional_instructions + правила вызова функций + карточка звонящего. Документы doc_* в живом разговоре не используются.

Поле	Куда попадает	Что писать
doc_who_am_i	оркестратор	Кто компания: название, город, чем занимается
doc_who_we_call	оркестратор	Целевая аудитория: кому звоним и зачем
doc_how_we_talk	оркестратор	Стиль общения бренда
doc_what_we_offer	оркестратор	Продукты/услуги, цены, условия
doc_rules_and_goals	оркестратор	Цели, KPI, ограничения
additional_instructions	оркестратор	Правила планирования и работы с контактами
voice_additional_instructions	голосовой	Поведение в живом разговоре: имя ассистента, манера речи, возражения
inbound_first_phrase	голосовой	Приветствие только для входящих звонков (≤500 символов)

Первая фраза исходящих звонков

Её генерирует оркестратор индивидуально под каждый звонок (стратегия PreCall) — статически она не настраивается. Влияйте на неё через doc_* и additional_instructions. Статическое поле inbound_first_phrase действует только на входящие.

Жизненный цикл звонка (PreCall → звонок → PostCall)

Каждый исходящий звонок проходит три фазы — понимание цикла — ключ к правильным промптам:

PreCall (оркестратор, без инструментов). Перед набором номера оркестратор получает задачу, карточку контакта, память о нём, полный транскрипт последнего звонка и хронологию всего общения (звонки + SMS + Telegram). На выходе — стратегия: первая фраза, тактика, тон, ключевые факты. Она передаётся голосовому агенту.
Живой разговор (голосовой агент). Говорит по стратегии PreCall. Документов doc_* и CRM-доступа у него нет — фактура приходит только через стратегию и базу знаний.
PostCall (оркестратор, с инструментами). Получает транскрипт и выполняет действия: всегда обновляет память о контакте; меняет стадию воронки только при реальном основании; для исходящих всегда планирует следующее касание, кроме случая достигнутой цели (недозвон → перезвон через 24 ч; ответил, но цель не достигнута → 1–3 дня, либо отложенное сообщение в Telegram); при важных событиях шлёт уведомление владельцу.

Итог звонка: SUCCESS / REJECTED / DO_NOT_CALL (только когда агент сам поставил эту стадию), FOLLOWUP (запланирован следующий шаг), ANSWERED (разговор без итога — контакт «В работе»), NO_ANSWER, ERROR (разбор не удался, стадия не менялась).

Стадии воронки: new → active → success / rejected / do_not_call.

Память о контакте: сводка, ключевые факты, лучшее время звонка, история тона — накапливается и автоматически попадает в контекст каждого следующего PreCall, PostCall и чата.

Инструменты оркестратора (чат с владельцем)

Владелец общается с оркестратором в чате на странице агента и (если подключён бот) в Telegram. Пустое условие = инструмент доступен всегда.

CRM: контакты

Инструмент	Что делает	Условие
create_agent_contact	Создать контакт (телефон обязателен)
bulk_create_contacts	Создать несколько контактов разом, дубли по номеру пропускаются
find_contact	Найти конкретного человека по имени, телефону или компании: любой порядок слов, ё/е, телефон в любом формате; нет точного совпадения — похожие (падеж, опечатка)
search_contacts	Поиск, отбор и подсчёт по фильтрам (стадии, попытки, давность звонка, дата добавления); постранично до 200 строк, точный total
get_agent_contacts	Общий список контактов
get_contact_details	Полная карточка: поля, стадия, заметки, память, попытки
get_contacts_by_stage	Разбивка контактов по стадиям воронки
update_contact_info	Перезаписать имя/компанию/должность/заметки
append_contact_note	Дописать заметку с датой, не стирая старые
move_contact_stage	Перевести контакт на стадию воронки
bulk_move_contacts_stage	Перевести группу контактов на стадию по фильтру
snooze_contact	Пауза до даты: отменяет запланированные звонки
delete_agent_contact	Удалить контакт (необратимо, по явной просьбе)

Планирование звонков

Инструмент	Что делает	Условие
create_agent_task	Запланировать звонок; сдвигается в рабочие часы
update_agent_task	Перенести/переименовать запланированный звонок
delete_agent_task	Отменить запланированный звонок (необратимо)
bulk_schedule_calls	Обзвон группы по фильтру с интервалом; пропускает дубли и «Не звонить»
bulk_cancel_calls	Отменить запланированные звонки группе контактов по фильтру
trigger_immediate_call	Позвонить прямо сейчас; ночью — в начале рабочих часов
get_agent_tasks	Список задач с фильтрами, проверка дублей
get_upcoming_schedule	Календарь ближайших звонков по всем контактам

Аналитика и история

Инструмент	Что делает	Условие
get_agent_stats	Сводная статистика: контакты, звонки, задачи
get_period_report	Отчёт за период: дозвоны, успехи, конверсия
get_failed_calls	Очередь недозвонов на перезвон
get_contact_call_history	История звонков контакта (кратко)
get_contact_timeline	Единая хронология: звонки + SMS + Telegram
get_call_transcript	Полный транскрипт конкретного звонка

Каналы и внешние системы

Инструмент	Что делает	Условие
send_sms	SMS клиенту с номера агента (до 500 символов)
send_telegram_notification	Уведомление ВЛАДЕЛЬЦУ в Telegram-бот агента	подключён бот
send_webhook	Событие (event + payload) на вебхук владельца	задан webhook_url
search_knowledge_base	Векторный поиск по базе знаний компании	создана база
telegram_send_message	Сообщение КЛИЕНТУ с личного Telegram владельца	личный аккаунт
telegram_get_thread	Прочитать переписку с клиентом в Telegram	личный аккаунт
schedule_telegram_message	Отложенное сообщение клиенту (передаётся инструкция, текст составится при отправке)	личный аккаунт
Google Calendar	Создать/найти/изменить/удалить событие, свободные слоты	коннектор
Gmail	Отправить/прочитать/ответить/переслать письмо	коннектор

Инструменты PostCall-анализа

После звонка оркестратору доступен сокращённый набор: update_contact_memory (всегда вызывается), create_agent_task, move_contact_stage, update_contact_info, send_telegram_notification, search_knowledge_base, send_sms, send_webhook + условные инструменты Telegram и коннекторов.

Функции голосового агента (в живом звонке)

Набор голосового агента намеренно маленький — он говорит, а не ведёт CRM:

Функция	Что делает	Условие
hangup_call	Завершить звонок с прощальной фразой
send_sms	SMS клиенту прямо во время звонка (адрес, ссылка, код)
search_pinecone	Поиск по базе знаний во время разговора	создана база
google_calendar_create_event / find_events	Записать на встречу / посмотреть календарь	коннектор
gmail_send_email / fetch_emails	Отправить/прочитать письмо с Gmail владельца	коннектор

Чего у голосового агента НЕТ (важно для промптов)

Нет CRM-инструментов, планирования задач, личного Telegram, вебхуков и документов doc_*. Если клиент просит перезвонить — агент уточняет время, а задачу ставит PostCall. Поэтому в voice_additional_instructions не нужно писать «запиши в CRM» или «поставь задачу» — это произойдёт автоматически. Пишите только про поведение в разговоре.

Каналы и автоматика вне звонков

Входящие звонки: голосовой агент отвечает (inbound_first_phrase), после разговора — тот же PostCall-анализ (перезвон планируется только при необходимости).
Входящие SMS: обрабатывает оркестратор — может ответить SMS, запланировать звонок, обновить память/стадию, уведомить владельца.
Входящие Telegram (личный аккаунт + автоответ): оркестратор отвечает клиенту как живой человек; охват — только контакты из базы или все входящие.
Отложенные Telegram-сообщения: живут в общем списке задач; перед отправкой оркестратор сверяется с контекстом — если договорённость уже закрыта, сообщение не отправляется.
Рабочие часы (МСК, по умолчанию 9–21; начало = конец — круглосуточно): вне окна клиенту не звонят и не пишут — звонки, сообщения Telegram/MAX, проверки ответа и trigger_immediate_call переносятся на утро. Контакту в стадии «Не звонить» ничего не планируется.
Вебхук: события (заявка, лид, результат звонка) POST-запросом на URL владельца — для n8n / Make / Zapier / CRM.
Планировщик проверяет задачи каждые ~30 секунд — «позвони сейчас» стартует в пределах полуминуты.

Гайд: как писать промпты

additional_instructions (оркестратор) — правила планирования и работы с базой в терминах реальных инструментов и стадий:

«Не звонить одному контакту чаще 1 раза в 3 дня»
«После двух недозвонов подряд отправляй SMS с предложением перезвонить»
«Отказников (rejected) не трогать 3 месяца»
«Горячих клиентов (просят счёт) — сразу уведомление владельцу»

voice_additional_instructions (голосовой агент) — только поведение в живом разговоре:

«Твоё имя — Алёна. Говори коротко, тепло, без канцелярита»
«Не называй цены на монтаж — предлагай замер»
«На возражение „дорого" — расскажи про рассрочку»
«Если просят человека — скажи, что менеджер перезвонит, и завершай звонок»

Не дублируйте базовый промпт

Уже встроено: русский язык, проверка дублей задач, время по МСК, «сначала читай данные — потом действуй», запрет выдумывать данные, автозавершение звонка (hangup_call), обновление CRM после звонка. Объёмную фактуру (каталог, прайс) кладите в базу знаний — её ищут и оркестратор, и голосовой агент.

Тарифы, кредиты и подключения

Через API не настраивается — всё делается в кабинете, но полезно для ответов пользователям:

Доступ к агенту: тестовый период 3 дня (единожды, +1500 кредитов) или тариф profi (+10 000 кредитов). Без доступа — 402 subscription_required.
Кредиты — валюта работы оркестратора: списываются за токены каждого вызова (PreCall, PostCall, чат, входящие) по ставкам выбранной модели. Баланс ниже 100 — оркестратор не запускается (402 insufficient_credits). Пакеты пополнения — на странице агента.
Голосовая часть оплачивается отдельно: собственные API-ключи провайдеров (OpenAI / Gemini / Cartesia / Yandex) + телефония Voximplant (номера, минуты, SMS).
Telegram-бот агента: уведомления владельцу + чат с оркестратором в Telegram.
Личный Telegram-аккаунт: агент пишет клиентам от имени владельца и отвечает на входящие; встроены анти-бан лимиты.
Коннекторы (Google Calendar, Gmail): OAuth-подключение на странице агента.
База знаний: создаётся на странице агента; наличие видно по has_knowledge_base.
Лимит: до 3 агентов; у каждого свои контакты, задачи, память и подключения.

GET /api/agent/list

Список агентов пользователя. Отсюда берётся agent_id (поле id) для остальных запросов.

curl -H "X-Api-Key: vfy_..." https://voicyfy.ru/api/agent/list

{
  "total": 1,
  "max_agents": 3,
  "can_create_more": true,
  "has_agent_access": true,
  "agents": [ { "id": "…", "name": "…", ... } ]
}

GET /api/agent/?agent_id={id}

Один агент со всеми настройками. Без agent_id возвращается первый (самый старый) агент. Перед редактированием всегда читайте текущее состояние этим запросом.

curl -H "X-Api-Key: vfy_..." "https://voicyfy.ru/api/agent/?agent_id=<uuid>"

GET /api/agent/orchestrator-models

Справочник моделей оркестратора. В поле orchestrator_model передавайте только slug из этого списка; если не передавать — применится модель по умолчанию.

{"models": [{"slug": "…", "name": "…", "description": "…"}], "default": "…"}

POST /api/agent/create

Создание агента. Все 5 документов обязательны.

curl -X POST https://voicyfy.ru/api/agent/create \
  -H "X-Api-Key: vfy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Алёна",
    "assistant_type": "openai",
    "doc_who_am_i": "Компания «АкваЛето», Иркутск...",
    "doc_who_we_call": "Частные домовладельцы, дачники...",
    "doc_how_we_talk": "Дружелюбно, на «вы»...",
    "doc_what_we_offer": "Бассейны Intex и Bestway от 15 000 ₽...",
    "doc_rules_and_goals": "Цель — записать на замер...",
    "voice_additional_instructions": "Твоё имя — Алёна.",
    "inbound_first_phrase": "Здравствуйте! Компания АкваЛето, меня зовут Алёна.",
    "working_hours_start": 9,
    "working_hours_end": 21,
    "voice": "marin"
  }'

Поле	Тип	Обяз.	Описание
name	string	Да	Имя агента (1–255)
assistant_type	string	Да	`gemini` \| `openai` \| `cartesia` \| `yandex`
doc_who_am_i … doc_rules_and_goals	string	Да (все 5)	Документы компании для оркестратора
additional_instructions	string	Нет	Доп. инструкции оркестратора
voice_additional_instructions	string	Нет	Доп. инструкции голосового агента
inbound_first_phrase	string	Нет	Приветствие входящих (≤500)
working_hours_start / _end	int 0–23	Нет	Рабочие часы (МСК), по умолчанию 9–21
orchestrator_model	string	Нет	Slug из /orchestrator-models
voice	string	Нет	Голос для gemini/openai/yandex (см. списки ниже)
cartesia_voice_id	string	Нет	ID голоса Cartesia (только cartesia)
voice_speed	float 0.5–1.5	Нет	Скорость речи (только cartesia)

Предусловия (выполняются пользователем в кабинете)

Верифицированная телефония Voximplant; API-ключ выбранного голосового провайдера в настройках; активный тариф или доступный триал; меньше 3 агентов. Иначе — ошибки 400/402 (см. ниже).

PUT /api/agent/?agent_id={id}

Редактирование агента. Передавайте только изменяемые поля — остальные не трогаются. Доступны все поля из create, а также:

Поле	Тип	Описание
is_active	bool	Включить/выключить агента
default_caller_id	string	Номер, с которого звонит агент
webhook_url	string ≤500	URL вебхука для событий во внешнюю систему
assistant_type	string	Смена голосового провайдера (нужен ключ нового провайдера)

curl -X PUT "https://voicyfy.ru/api/agent/?agent_id=<uuid>" \
  -H "X-Api-Key: vfy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "voice_additional_instructions": "Твоё имя — Алёна. Отвечай короче.",
    "inbound_first_phrase": "Добрый день! АкваЛето, Алёна слушает."
  }'

При изменении voice_additional_instructions промпт голосового агента пересобирается автоматически; изменения doc_* оркестратор подхватывает на лету.

Голоса по провайдерам

openai: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar; голоса GPT-Live: beacon, bossa, cinder, delta, gleam, meridian, quartz, ripple, stone, tempo, vesper, willow
gemini: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat
yandex: marina, dasha, alexander, julia, lera, masha, anton, kirill, filipp, ermil, jane, omazh, zahar, madi_ru, saule_ru
cartesia: голос задаётся через cartesia_voice_id + опционально voice_speed

Дефолты: openai — alloy, gemini — Kore, yandex — marina. Невалидное имя голоса в update → 400 invalid_voice.

Ошибки

Код	detail	Причина
401	`invalid_api_key`	Неверный или отозванный API-ключ
400	`telephony_not_verified`	Телефония Voximplant не верифицирована
400	`api_key_required_gemini/openai/cartesia/yandex`	Не задан ключ голосового провайдера в кабинете
400	`agent_limit_reached`	Уже 3 агента
400	`invalid_assistant_type / invalid_orchestrator_model / invalid_voice`	Невалидное значение поля
402	`subscription_required`	Триал использован, нужен тариф
404	`not_found`	Агент не найден (чужой или несуществующий agent_id)

Voicyfy Agent API