API голосовых роботов za|bota

Полное управление платформой из кода или ИИ-агента: создавать и править роботов (обычных по сценарию и AI на LLM), запускать обзвоны, читать расшифровки и строить отчёты. Все ответы — JSON.

Базовый адрес	`https://api.client.za-bota.com/v1`
Формат ответа	`{"status":"success"\|"error","message":…,"data":…}`. HTTP-код почти всегда 200 — смотрите на `status`.
Списки	постраничные: `data.data[]`, `data.current_page`, `data.last_page`, `data.total`; параметры `limit`, `page`
Идентификаторы	у всех сущностей есть `uuid` и числовой `id`; ручки раздела «Роботы: разбор и правка» принимают любой из них
Спецификация	openapi.json (OpenAPI 3.0) — можно скормить агенту как описание инструментов

Авторизация

Два способа. API-ключ — долгоживущий, для интеграций и агентов: создаётся в личном кабинете (Интеграции) или запросом POST /integrations. Сессия — POST /sessions с логином и паролем, возвращает token.

Заголовок (рекомендуется)

Authorization: Bearer <api_key или token>

Параметр запроса

GET /v1/bots?api_key=<api_key>
GET /v1/bots?token=<token>

Ключ даёт полный доступ к аккаунту: роботы, звонки, деньги. Храните его как пароль. Проверить ключ — GET /me.

Модель робота

Робот — это граф узлов (mind_map): массив объектов, каждый со своим id, типом action и переходами childs [{type, id, priority}]. Звонок начинается с узла call и идёт по переходам. Тип перехода зависит от узла: у интента — intent (совпало) и default (не совпало), у условия — true/false.

Обычный робот (по сценарию)Проиграл аудио → распознал ответ в переменную var_stageN_txt → прогнал по интентам-словарям → ветвление → следующее аудио или end_call. Корректировка = добавить слова в словарь интента, поменять аудио/текст, перевести переход. Всё это делается через PUT /bots/{uuid}/nodes/{id}.

AI-робот (на LLM)Тот же граф, но в цикле: слушает (audio_record) → ai_request к модели с промптом → синтез ответа → снова слушает. Промпт живёт в узле set_variables как $default_promt, инструкции — $default_instruction, анализ после звонка — $default_summarizing_request (возвращает JSON с полями результата). Корректировка = правка анкеты (PUT /bots/{uuid}/profile) для роботов из кабинета, или промпта напрямую (PUT /bots/{uuid}/prompt).

Пример узла обычного робота в компактном виде (GET /bots/{uuid}/graph?full=1):

{"id":73,"action":"intent","description":"нет",
 "intent":{"variable":"var_stage2_txt",
   "words_equal":["ничего не","не продаю","нет на продажу"],
   "words_in":["не нужно","не интересно","нет спасибо"],
   "words_not_in":["откуда номер"]},
 "childs":[{"type":"intent","id":70,"priority":1},{"type":"default","id":74,"priority":2}]}

Пример анкеты AI-робота (profile) — из неё платформа сама собирает промпты и JSON-анализ:

{"bot_name":"Анна","who":"Тебя зовут Анна, ты сотрудница кофейни «Утро»…","style":"Дружелюбно, коротко, без канцелярита",
 "rules":["Не обещай скидок","Если просят перезвонить — уточни время"],
 "facts":["Открытие 20 сентября","Промокод UTRO20 даёт 20%"],
 "plan":["Поздороваться и представиться","Узнать, удобно ли говорить","Пригласить на открытие","Продиктовать промокод","Попрощаться"],
 "stages":[2,3,4],
 "result_fields":[{"name":"pridet","type":"yes_no","hint":"собирается ли прийти"},{"name":"comment","type":"text","hint":"важное из разговора"}],
 "knowledge":{"uuid":"…"}}

Результат звонка хранится в переменных звонка: у обычного робота это то, что выставили узлы set_variables (например var_is_actual), у AI-робота — поля из result_fields анкеты плюс summary и stages_done. Ручки анализа отдают их в result, скрывая служебные поля движка.

Рецепты для агента

1. Ежедневный отчёт по роботу

GET /bots — список роботов
GET /bots/{uuid}/analytics?days=1 — итоги, статусы, поля результата, где обрывы
GET /bots/{uuid}/calls?days=1&status=answer&min_sec=20&with=transcript&limit=30 — прочитать разговоры
Сформулировать: что узнал робот, где теряет людей, что исправить

2. Корректировка обычного робота

analytics → exit_nodes: на каком узле чаще всего заканчиваются разговоры
GET /bots/{uuid}/calls?with=transcript: что реально говорят люди перед обрывом
GET /graph?node_id=73 — словарь интента
PUT /nodes/73 с dry_run=1, затем без — добавить фразы в words_in
GET /validate — граф цел

3. Корректировка AI-робота

GET /bots/{uuid}/profile (или /graph → prompt_slots)
Прочитать 20–30 расшифровок с result
PUT /bots/{uuid}/profile с merge=1: новые правила/факты/план — робот пересобирается сразу; либо PUT /prompt
POST /calls на свой номер — тест
GET /bot-profiles/{chain}/versions — откат, если стало хуже (render?version=N)

4. Новый AI-робот с нуля и обзвон

POST /bot-profiles/quick-start → черновик анкеты
POST /bot-profiles → chain_uuid
POST /bot-profiles/{chain}/render → робот
POST /calls — тест себе; послушать record_url, прочитать /calls/{uuid}/transcript
POST /contacts/categories + POST /contacts → список
POST /tasks → обзвон; следить по GET /tasks/{uuid} и analytics?task_id=

Правки узлов и анкет применяются к следующим звонкам сразу. Меняя робота, у которого идёт обзвон, сначала остановите задачу (PUT /tasks/{uuid} {"status":"stopped"}), проверьте тестовым звонком, затем возобновите.

Авторизация

GET`/me` Кто я

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

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/me' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"user_id":470,"role":"member","auth":"api_key","integration_id":157,
  "account":{"uuid":"…","number":"63011","balance":12500.5,"status":"active"},"bots":4}}

POST`/sessions` Войти по логину и паролю

Возвращает сессионный token (не истекает). Нужен только если у вас нет API-ключа. Без авторизации.

Параметр	Где	Тип	Описание
`phone`	body	string	телефон (или `email`, `name`, `telegram_id`)
`password` *	body	string	пароль

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/sessions' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"79991234567","password":"…"}'

Ответ (сокращённо)

{"status":"success","data":{"token":"3f9c…","user_id":470}}

GET`/integrations` Мои API-ключи

Список интеграций; поле api_key каждой — долгоживущий ключ.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/integrations' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"…","name":"Агент","api_key":"a1b2…","status":"enabled"}]}}

POST`/integrations` Создать API-ключ

Создаёт интеграцию с ключом. Ключ виден в ответе и в списке.

Параметр	Где	Тип	Описание
`name` *	body	string	имя интеграции
`status`	body	string	`enabled` (по умолчанию)

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/integrations' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Мой агент"}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","name":"Мой агент","api_key":"a1b2c3…","status":"enabled"}}

Роботы

GET`/bots` Список роботов

Постраничный список. Мои роботы и роботы подчинённых пользователей.

Параметр	Где	Тип	Описание
`limit`	query	int	на страницу (по умолчанию 200)
`page`	query	int	страница
`filter`	query	string	поиск по имени
`where`	query	json	фильтр `{"fl_ai":true}`

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots?limit=…&page=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"current_page":1,"last_page":3,"total":41,"data":[{"id":2272,"uuid":"6a16…","name":"ИИ магазин шин","fl_ai":true,"trunk_id":null}]}}

GET`/bots/{uuid}` Робот целиком

Вся запись, включая полный mind_map (граф). Для чтения структуры удобнее /bots/{uuid}/graph.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"id":2272,"uuid":"…","name":"…","mind_map":"[…]","config":{…},"fl_ai":true}}

POST`/bots` Создать робота

Создать робота с готовым графом. Валидации графа нет — перед сохранением проверьте его через /bots/{uuid}/validate с mind_map в теле. Для AI-робота проще идти через анкету (см. «AI-роботы»).

Параметр	Где	Тип	Описание
`name` *	body	string	имя
`mind_map` *	body	json	массив узлов (см. «Модель бота»)
`mind_map_cnt` *	body	int	максимальный id узла
`fl_ai`	body	bool	AI-робот
`trunk_uuid`	body	uuid	линия по умолчанию
`description`	body	string
`config`	body	json	`{"audio_record":true,…}`

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/bots' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Опрос","mind_map":[…],"mind_map_cnt":12,"fl_ai":false}'

Ответ (сокращённо)

{"status":"success","data":{"id":2275,"uuid":"…","name":"Опрос"}}

PUT`/bots/{uuid}` Изменить робота

Любые поля робота, в т.ч. целиком mind_map. Для точечных правок используйте /nodes/{id} — безопаснее.

Параметр	Где	Тип	Описание
`name`	body	string
`mind_map`	body	json	весь граф
`trunk_uuid`	body	uuid
`config`	body	json

Запрос

curl -X PUT 'https://api.client.za-bota.com/v1/bots/6a16a10e-…' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Опрос v2","trunk_uuid":"…"}'

Ответ (сокращённо)

{"status":"success","data":{"id":2275,"uuid":"…","name":"Опрос v2"}}

DELETE`/bots/{uuid}` Удалить робота

Мягкое удаление (deleted_at).

Запрос

curl -X DELETE 'https://api.client.za-bota.com/v1/bots/6a16a10e-…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"id":2275}}

GET`/dictionaries` Словари интентов

Переиспользуемые словари (words_equal/words_in/words_not_in), в т.ч. публичные платформенные (например, для автоответчика).

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/dictionaries' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"…","name":"Автоответчик","access":"public","words_in":[…]}]}}

Роботы: разбор и правка

GET`/bots/{uuid}/summary` Карточка робота

Краткая сводка без графа: тип (ai/classic), число узлов по типам, параметры LLM-узла, база знаний, линия, анкета (если есть), звонки за 30 дней. {uuid} — uuid или числовой id.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/summary' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"id":2272,"uuid":"…","name":"ИИ магазин шин","kind":"ai","nodes":68,
  "actions":{"ai_request":1,"set_variables":27,"condition":24,…},
  "ai":{"node_id":2,"provider":"openai","model":"gpt-4o","temperature":"0.7","knowledge_uuid":"…","fl_summarizing":true},
  "profile":null,"trunk":null,"last_30_days":{"calls":3,"answered":3,"last_call":"2026-09-07 13:10:36"}}}

GET`/bots/{uuid}/graph` Граф робота (компактно)

Узлы без пустых секций: id, action, description, переходы childs, и только те параметры, что относятся к типу узла. У AI-роботов дополнительно prompt_slots — тексты промптов, вытащенные из set_variables.

Параметр	Где	Тип	Описание
`full`	query	0\|1	полные словари интентов, промпты, HTTP-параметры
`node_id`	query	string	только эти узлы, через запятую (всегда полные)

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/graph?full=…&node_id=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"bot":{"id":2241,"kind":"classic"},"start_node_id":1,"nodes_total":16,"mind_map_cnt":100,
  "prompt_slots":[],
  "nodes":[{"id":1,"action":"call","childs":[{"type":"default","id":2,"priority":1}]},
   {"id":73,"action":"intent","description":"нет","childs":[{"type":"intent","id":70}],
    "intent":{"variable":"var_stage2_txt","words_equal":4,"words_in":98,"words_not_in":12,"sample":["ничего не","не продаю",…]}}]}}

GET`/bots/{uuid}/validate` Проверить граф

Список проблем: ошибки (битые переходы, пустое аудио, интент без переменной, нет стартового узла…) и предупреждения (узел без переходов, узел-сирота). POST с mind_map в теле проверяет граф ДО сохранения.

Параметр	Где	Тип	Описание
`mind_map`	body	json	проверить этот граф вместо сохранённого (POST)

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/validate' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"ok":false,"errors":1,"warnings":2,"problems":[
  {"level":"error","node_id":73,"code":"dangling_child","text":"переход на несуществующий узел 99999"},
  {"level":"warning","node_id":19,"code":"no_childs","text":"у узла нет переходов — звонок оборвётся здесь"}]}}

PUT`/bots/{uuid}/nodes/{node_id}` Изменить узел

Точечная правка одного узла. По умолчанию — слияние (mode=merge): переданные ключи перезаписывают, остальные сохраняются; вложенные объекты сливаются, массивы заменяются целиком. После правки граф проверяется; если у узла появились ошибки — не сохраняется (force=1 — сохранить всё равно). dry_run=1 — показать результат без записи.

Параметр	Где	Тип	Описание
`node` *	body	object	изменяемые поля узла (можно передать и без обёртки `node`)
`mode`	body	merge\|replace	`replace` — заменить узел целиком (id сохраняется)
`dry_run`	body	0\|1	не сохранять
`force`	body	0\|1	сохранить несмотря на ошибки

Запрос

curl -X PUT 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/nodes/73' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"node":{"description":"нет","intent":{"words_in":["не нужно","не интересно","нет спасибо","не актуально"]}}}'

Ответ (сокращённо)

{"status":"success","data":{"saved":true,"node":{"id":73,"action":"intent","intent":{…}},"before":{…},"check":{"ok":true,"errors":0,"warnings":3}}}

POST`/bots/{uuid}/nodes` Добавить узел

Новый узел получает следующий свободный id. parent_id + child_type — сразу прицепить к родителю (добавляется переход у родителя).

Параметр	Где	Тип	Описание
`node` *	body	object	узел: `action` обязателен, остальное по типу
`parent_id`	body	int	родитель
`child_type`	body	string	тип перехода у родителя (`default`, `intent`, `true`, `false`…)
`dry_run`	body	0\|1

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/nodes' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"parent_id":73,"child_type":"intent","node":{"action":"speech_synthesis","description":"прощание","text":"Поняла, спасибо, всего доброго!","tts_params":{"provider":"elevenlabs"},"childs":[{"type":"default","id":19,"priority":1}]}}'

Ответ (сокращённо)

{"status":"success","data":{"saved":true,"node":{"id":101,"action":"speech_synthesis",…},"check":{…}}}

DELETE`/bots/{uuid}/nodes/{node_id}` Удалить узел

Удаляет узел и все ссылки на него из childs/parents_id других узлов.

Параметр	Где	Тип	Описание
`dry_run`	query	0\|1

Запрос

curl -X DELETE 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/nodes/73' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"saved":true,"nodes_total":16,"check":{…}}}

PUT`/bots/{uuid}/prompt` Изменить промпт AI-робота

Прямая замена текста промпт-слота в узле set_variables (для роботов, собранных не через анкету). Текущие слоты и их тексты — в /graph → prompt_slots.

Параметр	Где	Тип	Описание
`name`	body	string	`default_promt` (по умолчанию), `default_instruction`, `default_summarizing_request`, `default_classifier_answer`
`text` *	body	string	новый текст (без `'''`)
`dry_run`	body	0\|1

Запрос

curl -X PUT 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/prompt' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"default_instruction","text":"#ВАЖНЫЕ ПРАВИЛА\n1. Не называй цены без уточнения размера…"}'

Ответ (сокращённо)

{"status":"success","data":{"saved":true,"node_id":42,"name":"default_instruction","length":812}}

AI-роботы и анкета

POST`/bot-profiles/quick-start` Быстрый старт: анкета по 3 ответам

LLM пишет черновик анкеты по описанию бизнеса, цели звонка и предложению. Ничего не сохраняет — поправьте и передайте в POST /bot-profiles.

Параметр	Где	Тип	Описание
`business` *	body	string	кто вы
`goal` *	body	string	цель звонка
`offer`	body	string	что предлагаете
`bot_name`	body	string	имя робота

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/bot-profiles/quick-start' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"business":"Сеть кофеен, открываем точку на Невском","goal":"пригласить гостей из базы на открытие","offer":"промокод на 20%","bot_name":"Анна"}'

Ответ (сокращённо)

{"status":"success","message":"llm","data":{"bot_name":"Анна","who":"Тебя зовут Анна, ты сотрудница кофейни «Утро»…","style":"Дружелюбно, коротко, без канцелярита",
 "rules":["Не обещай скидок","Если просят перезвонить — уточни время"],
 "facts":["Открытие 20 сентября","Промокод UTRO20 даёт 20%"],
 "plan":["Поздороваться и представиться","Узнать, удобно ли говорить","Пригласить на открытие","Продиктовать промокод","Попрощаться"],
 "stages":[2,3,4],
 "result_fields":[{"name":"pridet","type":"yes_no","hint":"собирается ли прийти"},{"name":"comment","type":"text","hint":"важное из разговора"}],
 "knowledge":{"uuid":"…"}}}

POST`/bot-profiles` Сохранить анкету (новая версия)

Анкета хранится цепочкой версий (chain_uuid). Первый вызов без chain_uuid создаёт цепочку, следующие — новую версию. Сохранение не меняет робота — нужен render.

Параметр	Где	Тип	Описание
`profile` *	body	object	анкета (см. пример)
`chain_uuid`	body	uuid	цепочка существующей анкеты
`note`	body	string	что изменили
`template_bot_id`	body	int	эталон (по умолчанию платформенный)

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/bot-profiles' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"profile":{"bot_name":"Анна","who":"Тебя зовут Анна, ты сотрудница кофейни «Утро»…","style":"Дружелюбно, коротко, без канцелярита", "rules":["Не обещай скидок","Если просят перезвонить — уточни время"], "facts":["Открытие 20 сентября","Промокод UTRO20 даёт 20%"], "plan":["Поздороваться и представиться","Узнать, удобно ли говорить","Пригласить на открытие","Продиктовать промокод","Попрощаться"], "stages":[2,3,4], "result_fields":[{"name":"pridet","type":"yes_no","hint":"собирается ли прийти"},{"name":"comment","type":"text","hint":"важное из разговора"}], "knowledge":{"uuid":"…"}},"note":"первая версия"}'

Ответ (сокращённо)

{"status":"success","data":{"chain_uuid":"0eaa…","version":1,"status":"draft","bot_id":null}}

POST`/bot-profiles/{chain_uuid}/render` Собрать робота из анкеты

Подставляет анкету в эталонный AI-сценарий и создаёт робота (или обновляет уже собранного по этой цепочке). version — откат на прошлую версию.

Параметр	Где	Тип	Описание
`version`	query	int	какую версию собрать (по умолчанию последнюю)

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/bot-profiles/0eaad2b0-…/render' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"profile":{"chain_uuid":"…","version":1,"status":"rendered"},"bot":{"id":2267,"uuid":"13e2…","name":"Анна"}}}

GET`/bot-profiles` Мои анкеты

Последняя версия каждой цепочки.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bot-profiles' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":[{"chain_uuid":"…","version":15,"status":"rendered","bot_id":2267,"profile":{…}}]}

GET`/bot-profiles/{chain_uuid}/versions` Версии анкеты

История версий с diff (changed) и источником (client, quickstart, moderator, rollback).

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bot-profiles/0eaad2b0-…/versions' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":[{"version":15,"source":"client","note":"…","changed":{…},"created_at":"…"}]}

GET`/bot-profiles/{chain_uuid}/funnel` Воронка по этапам разговора

Сколько дозвонов дошло до каждого этапа из plan/stages анкеты (по stages_done из анализа после звонка).

Параметр	Где	Тип	Описание
`days`	query	int	период, ≤92

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bot-profiles/0eaad2b0-…/funnel?days=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"answered":120,"analyzed":118,"rows":[{"code":"stage_1","title":"Узнать, удобно ли говорить","reached":118,"dropped_after":30,"drop_samples":[…]}]}}

GET`/bots/{uuid}/profile` Анкета робота

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

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/profile' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"chain_uuid":"…","version":15,"status":"rendered","profile":{…}}}

PUT`/bots/{uuid}/profile` Изменить анкету и пересобрать

Одним вызовом: новая версия анкеты + рендер в робота. merge=1 — передать только изменяемые ключи, остальные возьмутся из текущей версии.

Параметр	Где	Тип	Описание
`profile` *	body	object	анкета или её часть
`merge`	body	0\|1	частичное обновление
`note`	body	string	что изменили
`render`	body	0\|1	`0` — только сохранить

Запрос

curl -X PUT 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/profile' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"merge":1,"note":"добавили правило про скидки","profile":{"rules":["Не обещай скидок","Скидку даёт только менеджер"]}}'

Ответ (сокращённо)

{"status":"success","data":{"stored":{"version":16,"status":"rendered"},"rendered":{"bot":{"id":2267,"uuid":"…"}}}}

GET`/knowledge` Базы знаний

Документы для RAG. Привязка к роботу — knowledge.uuid в анкете или ai_request_params.knowledge_uuid в узле.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/knowledge' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"b27e…","name":"Прайс и условия","status":"active","link":"…"}]}}

POST`/knowledge` Добавить базу знаний

Ссылка на документ (Google Doc/файл); индексируется фоново, статус смотрите в GET /knowledge/{uuid}.

статусы: update → indexing → active; error — документ не прочитался

Параметр	Где	Тип	Описание
`name` *	body	string
`link` *	body	string	ссылка на документ
`description`	body	string

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/knowledge' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Прайс","link":"https://docs.google.com/document/d/…"}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","status":"update"}}

Обзвон и звонки

GET`/trunks` Линии (транки)

Свои SIP-линии. Для звонка нужна trunk_uuid линии или номер платформы.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/trunks' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"…","name":"Mango","status":"active"}]}}

POST`/contacts/categories` Создать список обзвона

Категория = список контактов для задачи. GET /contacts/categories — мои списки с числом контактов (contacts_qnt).

Параметр	Где	Тип	Описание
`name` *	body	string
`comments`	body	string

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/contacts/categories' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"База сентябрь"}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","id":901,"name":"База сентябрь"}}

POST`/contacts` Добавить контакт

Контакт в список. variables доступны роботу как $first_name и т.д.

Параметр	Где	Тип	Описание
`phone` *	body	string	нормализуется к формату 7XXXXXXXXXX
`category_uuid` *	body	uuid	список (категория)
`name1`	body	string	имя → роботу как `$first_name`
`name2`	body	string	отчество
`name3`	body	string	фамилия
`fullname`	body	string
`email`	body	string
`company`	body	string
`city`	body	string
`more_data`	body	json	произвольные поля

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/contacts' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"79991234567","category_uuid":"…","name1":"Иван","company":"ООО Ромашка"}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","phone":"79991234567","category_id":901}}

POST`/imports/upload` Загрузить контакты файлом

CSV/XLSX; дальше POST /imports с картой колонок. Для небольших списков проще POST /contacts по одному.

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/imports/upload' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

POST`/tasks` Создать задачу обзвона

Задача = робот + список + линия + параметры дозвона. Создаётся в статусе created, конвейер платформы сам разворачивает её в звонки. Остановить — PUT со status=stopped, возобновить — active.

Параметр	Где	Тип	Описание
`name` *	body	string
`bot_uuid` *	body	uuid
`contact_category_uuid` *	body	uuid	список
`trunk_uuid`	body	uuid	линия
`more_data`	body	json	`{"call_params":{"attempts":"2","time_retries":"3","delayed":false}}` — попыток и часов между ними
`notify_email`	body	string	письмо по завершении

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/tasks' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Открытие — база сентябрь","bot_uuid":"…","contact_category_uuid":"…","trunk_uuid":"…","more_data":{"call_params":{"attempts":"2","time_retries":"3"}}}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","id":17250,"status":"created","qnt_calls":0}}

GET`/tasks/{uuid}` Задача

Статус и счётчики: qnt_calls, qnt_calls_finished.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/tasks/6a16a10e-…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","status":"active","qnt_calls":500,"qnt_calls_finished":212}}

PUT`/tasks/{uuid}` Остановить / возобновить

Параметр	Где	Тип	Описание
`status` *	body	string	`stopped` \| `active`

Запрос

curl -X PUT 'https://api.client.za-bota.com/v1/tasks/6a16a10e-…' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status":"stopped"}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","status":"stopped"}}

POST`/calls` Позвонить одному номеру

Тестовый звонок себе или звонок по событию (заявка с сайта). Учитывает тихие часы (→ planned) и чёрный список (→ blocked).

Параметр	Где	Тип	Описание
`phone` *	body	string
`bot_uuid` *	body	uuid
`trunk_uuid`	body	uuid
`variables`	body	json	переменные для робота: `first_name`, свои поля
`attempts`	body	int	попыток
`time_retries`	body	string	`30m`, `1h`, `1d`
`delayed_at`	body	datetime	позвонить не раньше

Запрос

curl -X POST 'https://api.client.za-bota.com/v1/calls' \
  -H 'Authorization: Bearer $ZABOTA_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"79991234567","bot_uuid":"…","variables":{"first_name":"Иван"}}'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"8a34…","status":"created"}}

GET`/contacts/blacklist` Чёрный список

Номера, которым не звоним. POST с phone — добавить, DELETE /{uuid} — убрать.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/contacts/blacklist' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"…","phone":"7999…"}]}}

Анализ и отчёты

GET`/bots/{uuid}/analytics` Аналитика робота

Всё для отчёта по одному роботу за период: итоги, статусы, длительности, по дням, распределение полей результата (что робот узнал), узлы, на которых заканчиваются разговоры (exit_nodes — где обрыв у обычных ботов), этапы разговора (stages — для роботов из анкеты).

Параметр	Где	Тип	Описание
`days`	query	int	период назад (по умолчанию 30, ≤92)
`from`	query	date	`YYYY-MM-DD`
`to`	query	date
`task_id`	query	int	только одна задача
`sample`	query	int	сколько дозвонов разбирать для распределений (≤5000)

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/analytics?days=…&from=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"bot":{"id":2241,"kind":"classic"},"from":"2026-08-10","to":"2026-09-08",
  "totals":{"calls":2623,"answered":1791,"answer_rate":68.3,"answered_30s":171,"unique_phones":2074,"minutes":450.5,"avg_sec":13.4,"cost":7876.3},
  "by_status":{"answer":1791,"noanswer":307,"voicemail":248,"busy":213,"error":59},
  "duration_buckets":{"lt10":657,"10_30":963,"30_60":171,"60_180":0,"gt180":0},
  "daily":[{"day":"2026-09-07","calls":756,"answered":617,"minutes":110.1,"cost":2255.2}],
  "result_fields":[{"field":"var_is_actual","filled":1791,"empty":0,"distinct":2,"values":{"false":1620,"true":171}}],
  "exit_nodes":[{"node_id":19,"count":900,"action":"end_call","description":"тишина"}],
  "stages":[]}}

GET`/bots/{uuid}/calls` Звонки робота

Список звонков с результатом (поля, которые робот узнал) и ссылкой на запись. with=transcript добавляет расшифровку разговора.

Параметр	Где	Тип	Описание
`days`	query	int
`from`	query	date
`to`	query	date
`status`	query	string	через запятую: `answer,noanswer`
`task_id`	query	int
`phone`	query	string	поиск по номеру
`min_sec`	query	int	не короче N секунд
`with`	query	string	`transcript`, `track`
`limit`	query	int	≤500
`offset`	query	int

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/bots/6a16a10e-…/calls?days=…&from=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"total":182,"items":[{"uuid":"8a34…","created_at":"2026-09-07 13:10:36","phone":"7901…","status":"answer","bill_sec":262,"cost":21.86,
  "result":{"summary":"Клиент согласился на зимние шины APLUS 275/45 R20","var_is_actual":"1","client_name":""},
  "record_url":"https://client.za-bota.com/calls/storage/3497/8a34…/….mp3",
  "transcript":{"source":"dialog","turns":[{"who":"bot","text":"Добрый день! Меня зовут Дмитрий…"},{"who":"human","text":"Здравствуйте, мне нужны шины на Ауди…"}]}}]}}

GET`/calls/{uuid}/transcript` Разбор одного звонка

Расшифровка, результат, маршрут по узлам (path), расход LLM/TTS/STT (usage), запись.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/calls/6a16a10e-…/transcript' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"uuid":"…","status":"answer","bill_sec":262,"cost":21.86,"bot":{"id":2272,"kind":"ai"},
  "transcript":{"source":"dialog","turns":[…]},"result":{…},"stages_done":["stage_1","stage_2"],
  "path":[{"node_id":1,"action":"call"},{"node_id":2,"action":"ai_request","description":"ai_answer"}],
  "usage":{"llm":{"requests":13,"prompt_tokens":41200,"completion_tokens":900,"cached_tokens":30000,"from_cache":2},"tts":{"requests":12,"chars":1400,"from_cache":5},"stt":{"requests":12,"seconds":95}},
  "record_url":"…"}}

GET`/calls` Все звонки (штатный список)

Постраничный список по всем роботам с фильтрами. Для отчёта по одному роботу быстрее /bots/{uuid}/calls.

Параметр	Где	Тип	Описание
`date_start`	query	date
`date_end`	query	date
`status`	query	string
`where`	query	json	`{"bot_id":2241}`
`limit`	query	int
`page`	query	int
`full_variables`	query	0\|1	все переменные звонка

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/calls?date_start=…&date_end=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"total":2623,"data":[{"uuid":"…","status":"answer","bill_sec":30,"cost":6.6,"bot_name":"…","task_name":"…","variables":{…}}]}}

GET`/calls/report` Выгрузка звонков CSV

Те же фильтры, что у /calls; ответ — CSV (windows-1251) со всеми переменными.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/calls/report' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

GET`/statistics/dashboard` Дашборд аккаунта

Счётчики контактов/звонков/баланса и график за 12 месяцев.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/statistics/dashboard' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

GET`/accounts` Счёт и баланс

Лицевой счёт: balance, status. Отрицательный баланс блокирует задачи.

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/accounts' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Ответ (сокращённо)

{"status":"success","data":{"data":[{"uuid":"…","number":"63011","balance":12500.5,"status":"active"}]}}

GET`/finance` Операции по счёту

Пополнения и списания.

Параметр	Где	Тип	Описание
`date_start`	query	date
`date_end`	query	date

Запрос

curl -X GET 'https://api.client.za-bota.com/v1/finance?date_start=…&date_end=…' \
  -H 'Authorization: Bearer $ZABOTA_KEY'

Справочник: типы узлов (`action`)

action	Название	Ключевые поля
`call`	Старт звонка	Первый узел любого сценария. `voicemail_detection_params` — определение автоответчика.
`audio_play`	Проиграть аудио	`audio.uuid`/`filename` — файл из `/files`, `audio.from_variable` — файл из переменной, `audio.can_interrupt` — можно перебить.
`speech_synthesis`	Синтез речи	`text` (можно `$переменные`), `tts_params.provider` (`elevenlabs`, `sber`…), `id` голоса, `speed`, `emotion`.
`audio_transcription`	Распознать речь	Слушает абонента, кладёт текст в `stt_params.variable_name` (обычно `var_stageN_txt`). `max_silence_begin/end` — таймауты тишины.
`audio_record`	Запись реплики	Как `audio_transcription`, но в AI-цикле: `record.variable_name`, `record.max_duration`.
`intent`	Интент (словарь)	Проверяет переменную по словам: `intent.variable`, `words_equal` (точные фразы), `words_in` (вхождения), `words_not_in` (исключения). Переход `childs[type=intent]` при совпадении.
`condition`	Условие	`condition.operation` — выражение над переменными (`$var_is_actual == 'true'`), переходы `true/false`.
`set_variables`	Переменные	`set_variables` — код присваиваний: `$a = '1'; $b += '…';`. У AI-ботов здесь лежат промпт-слоты `$default_promt`, `$default_instruction`, `$default_summarizing_request`.
`http_request`	HTTP-запрос	`http_request_params.url/method/header/data`, `variables` — куда положить ответ, `wait_response`.
`ai_request`	Запрос к LLM	`ai_request_params`: `provider`, `model`, `temperature`, `system_message`, `user_message`, `variable_name`, база знаний `fl_knowledge`+`knowledge_uuid`+`knowledge_request`, анализ после звонка `fl_summarizing`+`summarizing_request`, классификаторы.
`goto`	Переход	Безусловный прыжок на узел `next_action`.
`event_wait`	Ожидание события	Ждёт внешнего события/таймера (`event_wait_params`).
`call_redirect`	Перевод звонка	`call_redirect_params.phone_number`, `play_notify`.
`digital_input`	Донабор (DTMF)	`digital_input_params.digitals` — ожидаемые цифры.
`message_send`	Сообщение	SMS/WhatsApp/TG: `message_send.text`, `channel_code`, `provider`, `phone`.
`end_call`	Завершить звонок	Конечный узел.

Полный список — GET /actions. Узел в базе хранится «плоско»: все секции всех типов присутствуют, незадействованные равны null; при правке через /nodes достаточно передавать только нужные.

Справочник: статусы

Звонок (calls.status)

`created`	создан, ждёт очереди
`planned`	вне «тихих часов» абонента (09–21 по его времени), позвоним позже
`delayed`	отложен до `delayed_at`
`queued`	в очереди на АТС
`ringing`	идёт дозвон
`in_progress`	разговор идёт
`retry`	ждёт повторной попытки
`answer`	дозвон, разговор состоялся (тарифицируется)
`noanswer`	не ответил
`busy`	занято
`voicemail`	автоответчик (бесплатно)
`congestion`	сеть недоступна
`chanunavail`	канал недоступен
`error`	ошибка (кривой номер и т.п.)
`blocked`	номер в чёрном списке
`cancel`	отменён

Задача обзвона (tasks.status)

`created`	создана
`preparing`	формируется список звонков
`active`	идёт обзвон
`stopped`	остановлена
`success`	завершена
`canceled`	отменена
`blocked`	заблокирована (нет денег/модерация)
`error`	ошибка

Тарифицируются только звонки answer по bill_sec. Недозвон, занято и автоответчик бесплатны.

Ошибки и лимиты

message	Что значит
`the token cannot be empty`	нет ключа/токена
`bad api_key` / `bad token`	ключ не найден или отключён
`operation denied`	объект принадлежит другому аккаунту
`bot not found` / `node not found`	нет такого робота/узла (или удалён)
`node has errors`	правка сломала бы граф; список в `data.problems`, можно `force=1`
`bot has no profile`	робот собран не из анкеты — правьте через `/graph`, `/nodes`, `/prompt`

Периоды аналитики — до 92 дней; распределения считаются по выборке до 5000 дозвонов. Списки звонков — до 500 за запрос, дальше offset. Ключ действует без срока; отключить — PUT /integrations/{uuid} {"status":"disabled"}.

API голосовых роботов za|bota

Авторизация

Модель робота

Рецепты для агента

Авторизация

GET/me Кто я

POST/sessions Войти по логину и паролю

GET/integrations Мои API-ключи

POST/integrations Создать API-ключ

Роботы

GET/bots Список роботов

GET/bots/{uuid} Робот целиком

POST/bots Создать робота

PUT/bots/{uuid} Изменить робота

DELETE/bots/{uuid} Удалить робота

GET/dictionaries Словари интентов

Роботы: разбор и правка

GET/bots/{uuid}/summary Карточка робота

GET/bots/{uuid}/graph Граф робота (компактно)

GET/bots/{uuid}/validate Проверить граф

PUT/bots/{uuid}/nodes/{node_id} Изменить узел

POST/bots/{uuid}/nodes Добавить узел

DELETE/bots/{uuid}/nodes/{node_id} Удалить узел

PUT/bots/{uuid}/prompt Изменить промпт AI-робота

AI-роботы и анкета

POST/bot-profiles/quick-start Быстрый старт: анкета по 3 ответам

POST/bot-profiles Сохранить анкету (новая версия)

POST/bot-profiles/{chain_uuid}/render Собрать робота из анкеты

GET/bot-profiles Мои анкеты

GET/bot-profiles/{chain_uuid}/versions Версии анкеты

GET/bot-profiles/{chain_uuid}/funnel Воронка по этапам разговора

GET/bots/{uuid}/profile Анкета робота

PUT/bots/{uuid}/profile Изменить анкету и пересобрать

GET/knowledge Базы знаний

POST/knowledge Добавить базу знаний

Обзвон и звонки

GET/trunks Линии (транки)

POST/contacts/categories Создать список обзвона

POST/contacts Добавить контакт

POST/imports/upload Загрузить контакты файлом

POST/tasks Создать задачу обзвона

GET/tasks/{uuid} Задача

PUT/tasks/{uuid} Остановить / возобновить

POST/calls Позвонить одному номеру

GET/contacts/blacklist Чёрный список

Анализ и отчёты

GET/bots/{uuid}/analytics Аналитика робота

GET/bots/{uuid}/calls Звонки робота

GET/calls/{uuid}/transcript Разбор одного звонка

GET/calls Все звонки (штатный список)

GET/calls/report Выгрузка звонков CSV

GET/statistics/dashboard Дашборд аккаунта

GET/accounts Счёт и баланс

GET/finance Операции по счёту

Справочник: типы узлов (action)

Справочник: статусы

Ошибки и лимиты

GET`/me` Кто я

POST`/sessions` Войти по логину и паролю

GET`/integrations` Мои API-ключи

POST`/integrations` Создать API-ключ

GET`/bots` Список роботов

GET`/bots/{uuid}` Робот целиком

POST`/bots` Создать робота

PUT`/bots/{uuid}` Изменить робота

DELETE`/bots/{uuid}` Удалить робота

GET`/dictionaries` Словари интентов

GET`/bots/{uuid}/summary` Карточка робота

GET`/bots/{uuid}/graph` Граф робота (компактно)

GET`/bots/{uuid}/validate` Проверить граф

PUT`/bots/{uuid}/nodes/{node_id}` Изменить узел

POST`/bots/{uuid}/nodes` Добавить узел

DELETE`/bots/{uuid}/nodes/{node_id}` Удалить узел

PUT`/bots/{uuid}/prompt` Изменить промпт AI-робота

POST`/bot-profiles/quick-start` Быстрый старт: анкета по 3 ответам

POST`/bot-profiles` Сохранить анкету (новая версия)

POST`/bot-profiles/{chain_uuid}/render` Собрать робота из анкеты

GET`/bot-profiles` Мои анкеты

GET`/bot-profiles/{chain_uuid}/versions` Версии анкеты

GET`/bot-profiles/{chain_uuid}/funnel` Воронка по этапам разговора

GET`/bots/{uuid}/profile` Анкета робота

PUT`/bots/{uuid}/profile` Изменить анкету и пересобрать

GET`/knowledge` Базы знаний

POST`/knowledge` Добавить базу знаний

GET`/trunks` Линии (транки)

POST`/contacts/categories` Создать список обзвона

POST`/contacts` Добавить контакт

POST`/imports/upload` Загрузить контакты файлом

POST`/tasks` Создать задачу обзвона

GET`/tasks/{uuid}` Задача

PUT`/tasks/{uuid}` Остановить / возобновить

POST`/calls` Позвонить одному номеру

GET`/contacts/blacklist` Чёрный список

GET`/bots/{uuid}/analytics` Аналитика робота

GET`/bots/{uuid}/calls` Звонки робота

GET`/calls/{uuid}/transcript` Разбор одного звонка

GET`/calls` Все звонки (штатный список)

GET`/calls/report` Выгрузка звонков CSV

GET`/statistics/dashboard` Дашборд аккаунта

GET`/accounts` Счёт и баланс

GET`/finance` Операции по счёту

Справочник: типы узлов (`action`)