{"openapi":"3.1.0","info":{"title":"Vetka Bot API","version":"1.0.0","description":"API платформы Ветка для ботов, каналов, входящих сообщений, inbox и интеграций."},"servers":[{"url":"https://api.vetkabot.ru","description":"Production API"}],"tags":[{"name":"Auth","description":"Регистрация и вход в кабинет"},{"name":"Bots","description":"Управление ботами пользователя"},{"name":"Bot Runtime","description":"Методы для backend вашего бота"},{"name":"Channels","description":"Каналы и конфигурация интеграций"},{"name":"Messages","description":"Входящие сообщения из внешних источников"},{"name":"WordPress","description":"Интеграция Contact Form 7 / WordPress"},{"name":"Inbox","description":"Операторский inbox платформы"},{"name":"Widget","description":"Публичная конфигурация web widget"}],"components":{"securitySchemes":{"userBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Токен пользователя для доступа к кабинету и inbox"},"botBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Bot Token","description":"Токен бота для runtime-методов send-message, get-updates и webhook"}},"schemas":{"AuthRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":6}}},"BotCreateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"webhook_url":{"type":"string","format":"uri","nullable":true}}},"IncomingMessageRequest":{"type":"object","required":["text"],"properties":{"bot_id":{"type":"string","format":"uuid"},"widget_key":{"type":"string"},"text":{"type":"string"},"chat_id":{"type":"string"},"user_id":{"type":"string"},"timestamp":{"type":"integer"},"channel":{"type":"string","enum":["web","website","widget","wordpress","crm","email","mobile_app","custom_api"]},"external_chat_id":{"type":"string"},"external_user_id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}},"metadata":{"type":"object","additionalProperties":true}}},"SendMessageRequest":{"type":"object","required":["chat_id","text"],"properties":{"chat_id":{"type":"string"},"text":{"type":"string"},"channel":{"type":"string"},"reply_markup":{"type":"object","additionalProperties":true}}},"WordPressSubmissionRequest":{"type":"object","required":["integration_key"],"properties":{"integration_key":{"type":"string"},"site_url":{"type":"string","format":"uri"},"page_url":{"type":"string","format":"uri"},"form_id":{"type":"string"},"form_title":{"type":"string"},"contact_email":{"type":"string","format":"email"},"contact_phone":{"type":"string"},"contact_name":{"type":"string"},"fields":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}]}}}},"ConversationMetaPatch":{"type":"object","properties":{"status":{"type":"string","enum":["new","open","waiting","closed"]},"operator_note":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"}}}}},"paths":{"/api/auth/register":{"post":{"tags":["Auth"],"summary":"Регистрация пользователя","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequest"}}}},"responses":{"200":{"description":"Пользователь зарегистрирован и вошел в систему"}}}},"/api/auth/login":{"post":{"tags":["Auth"],"summary":"Вход в кабинет","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthRequest"}}}},"responses":{"200":{"description":"Успешный вход"}}}},"/api/bots":{"get":{"tags":["Bots"],"summary":"Получить список ботов пользователя","security":[{"userBearerAuth":[]}],"responses":{"200":{"description":"Список ботов"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Bots"],"summary":"Создать нового бота","security":[{"userBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotCreateRequest"}}}},"responses":{"201":{"description":"Бот создан"}}}},"/api/bots/{id}/channels":{"get":{"tags":["Channels"],"summary":"Получить список каналов бота","security":[{"userBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Каналы бота"}}},"patch":{"tags":["Channels"],"summary":"Включить канал или обновить его конфигурацию","security":[{"userBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel_type"],"properties":{"channel_type":{"type":"string"},"is_active":{"type":"boolean"},"config":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Канал обновлен"}}}},"/api/bots/{id}/get-updates":{"get":{"tags":["Bot Runtime"],"summary":"Получить входящие события бота","description":"Аналог long polling / getUpdates для backend вашего бота.","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://api.vetkabot.ru/api/bots/{bot_id}/get-updates?offset=0&limit=100\" \\\n  -H \"Authorization: Bearer {API_TOKEN}\""}],"security":[{"botBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}},{"name":"timeout","in":"query","required":false,"schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Список обновлений"}}}},"/api/bots/{id}/send-message":{"post":{"tags":["Bot Runtime"],"summary":"Отправить сообщение пользователю","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.vetkabot.ru/api/bots/{bot_id}/send-message\" \\\n  -H \"Authorization: Bearer {API_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"chat_id\": \"client_123\",\n    \"text\": \"Здравствуйте! Чем могу помочь?\",\n    \"channel\": \"web\"\n  }'"}],"security":[{"botBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"200":{"description":"Сообщение принято в доставку"}}}},"/api/bots/{id}/set-webhook":{"post":{"tags":["Bot Runtime"],"summary":"Установить webhook для бота","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.vetkabot.ru/api/bots/{bot_id}/set-webhook\" \\\n  -H \"Authorization: Bearer {API_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://client-backend.ru/webhook\"\n  }'"}],"security":[{"botBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Webhook установлен"}}}},"/api/messages":{"post":{"tags":["Messages"],"summary":"Передать входящее сообщение в платформу","description":"Используется сайтом, внешним frontend, custom API или прокси-слоем для доставки сообщений в Ветку.","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.vetkabot.ru/api/messages\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"bot_id\": \"{bot_id}\",\n    \"text\": \"Хочу узнать стоимость\",\n    \"channel\": \"web\",\n    \"external_chat_id\": \"site-chat-42\",\n    \"external_user_id\": \"lead-42\",\n    \"user\": {\n      \"first_name\": \"Анна\"\n    },\n    \"metadata\": {\n      \"page_url\": \"https://example.ru/pricing\",\n      \"page_title\": \"Тарифы\"\n    }\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingMessageRequest"}}}},"responses":{"200":{"description":"Сообщение принято"},"400":{"description":"Ошибка валидации","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/widget/config":{"get":{"tags":["Widget"],"summary":"Получить конфигурацию виджета","parameters":[{"name":"widget_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Публичная конфигурация widget"}}}},"/api/integrations/wordpress/contact-form-7":{"post":{"tags":["WordPress"],"summary":"Отправить заявку из Contact Form 7 в платформу","x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://api.vetkabot.ru/api/integrations/wordpress/contact-form-7\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"integration_key\": \"{integration_key}\",\n    \"site_url\": \"https://client-site.ru\",\n    \"page_url\": \"https://client-site.ru/contact\",\n    \"form_title\": \"Заявка с сайта\",\n    \"contact_name\": \"Иван\",\n    \"contact_email\": \"ivan@example.com\",\n    \"fields\": {\n      \"service\": \"Поддержка сайта\",\n      \"comment\": \"Нужна консультация\"\n    }\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSubmissionRequest"}}}},"responses":{"200":{"description":"Заявка принята"}}}},"/api/inbox":{"get":{"tags":["Inbox"],"summary":"Получить список диалогов оператора","security":[{"userBearerAuth":[]}],"parameters":[{"name":"bot_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Список диалогов"}}}},"/api/inbox/{id}":{"get":{"tags":["Inbox"],"summary":"Получить детали диалога","security":[{"userBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Диалог с сообщениями и контактами"}}},"post":{"tags":["Inbox"],"summary":"Отправить ручной ответ из inbox","security":[{"userBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Ручной ответ отправлен"}}},"patch":{"tags":["Inbox"],"summary":"Обновить статус или заметку диалога","security":[{"userBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMetaPatch"}}}},"responses":{"200":{"description":"Карточка диалога обновлена"}}}}}}