Вебхуки та API Sviteya — інструкція для клієнтів

Підходить для: конструкторів сайтів (WordPress, Webflow), CRM, Zapier, Make, Google Forms — будь-якої системи, яка вміє надіслати POST-запит.

1. Відкрий воронку в редакторі.
2. Додай тригер «Вхідний вебхук» (панель тригерів унизу).
3. Збережи воронку — у налаштуваннях тригера з’явиться твоя персональна адреса вигляду:

https://app.sviteya.ai/api/hooks/AbCdEf123456789xYz

Токен у адресі — секретний: хто знає адресу, той може запускати воронку. Не публікуй її у відкритому коді сторінки, якщо цього можна уникнути.

POST https://app.sviteya.ai/api/hooks/<твій_токен>
Content-Type: application/json

Ключ API для цієї адреси не потрібен: секрет — сам токен в адресі.

Тіло — JSON. У ньому має бути те, за чим Sviteya знайде людину:

Немає жодного з цих полів — людину можна знайти за будь-яким іншим полем запиту, наприклад поштою чи телефоном. Для цього в тригері заповни рядок «кого шукати»: яке поле запиту порівнювати і з яким полем контакта. Якщо за значенням знайдеться кілька людей, Sviteya нічого не робить, а причину покаже в «Журналі вебхуків».

Решта полів — будь-які твої дані:

{
  "telegramId": "123456789",
  "email": "client@example.com",
  "tariff": "premium",
  "sum": 500
}

1. Sviteya знайде контакта у боті цієї воронки.
2. Запише дані з запиту у змінні контакта або бали — згідно з мапінгом, який ти налаштувала в тригері («поле з вебхука → куди в сервісі»).
3. Запустить воронку для цього контакта.

Усі запити й причини відмов видно в «Журналі вебхуків» у налаштуваннях тригера.

• Підпис. У тригері можна ввімкнути галочку «Вимагати підпис (HMAC-SHA256)». Тоді кожен запит має нести заголовок x-sviteya-signature: HMAC-SHA256 від тіла запиту секретом з тригера (hex). Без правильного підпису — відповідь 401.
• Повтори. Якщо надіслати той самий запит двічі (з тим самим заголовком x-idempotency-key, полем event_id або просто тим самим тілом), воронка запуститься лише один раз.

Дія «Webhooks → POST», адреса з кроку 1, тип даних JSON, у тілі — telegramId зі свого джерела (наприклад, зі змінної, яку бот записав у CRM раніше) + потрібні поля.

<script>
fetch('https://app.sviteya.ai/api/hooks/ТВІЙ_ТОКЕН', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ telegramId: '123456789', source: 'landing' })
});
</script>

Інтеграції → картка «Claude / MCP та API-ключі» → «Створити ключ». Ключ, створений у кабінеті, — повний: усі дії, які дозволяє твоя роль. Створювати ключі можуть власник і адміністратор акаунта. Для Claude ключ не потрібен — він підключається через OAuth. Ключ показується один раз — збережи його.

Ключ належить акаунту, у якому ти його створила. Перемкнулась на інший акаунт — ключ усе одно працює зі СВОЇМ: інтеграція клієнта A не побачить даних клієнта B. Біля кожного ключа в списку написано, якому акаунту він належить (у кабінеті список показує ключі з усіх твоїх акаунтів, тож будь-який можна відкликати; а сам ключ через API бачить і відкликає лише ключі свого акаунта і не знає про інші твої акаунти). Права ключа — це твоя роль у ЦЬОМУ акаунті просто зараз: якщо роль знизили, ключ звузиться одразу; якщо тебе видалили з акаунта, ключ перестає працювати і стирається. Старі ключі (до 04.10.2026) прив’язані до акаунта, який був активним у момент оновлення; ключ без акаунта треба створити заново.

Кожен запит — із заголовком:

Authorization: Bearer <твій_ключ>

База: https://app.sviteya.ai/api

Список ботів (botId для решти запитів):

GET /api/bots

Контакти бота (пошук за іменем/username/Telegram ID):

GET /api/bots/<botId>/contacts?search=Олена

Картка контакта:

GET /api/bots/<botId>/contacts/<contactId>

Повісити/зняти тег:

POST   /api/bots/<botId>/contacts/<contactId>/tags   {"tagId": "..."}
DELETE /api/bots/<botId>/contacts/<contactId>/tags/<tagId>

Записати значення змінної контакта:

PUT /api/bots/<botId>/contacts/<contactId>/fields/<fieldId>   {"value": "..."}

Надіслати повідомлення контакту від бота:

POST /api/bots/<botId>/contacts/<contactId>/send   {"text": "Привіт!"}

Запустити воронку для контакта:

POST /api/flows/<flowId>/start   {"telegramId": "123456789"}

Знайти контакта за Telegram ID: GET /api/bots/<botId>/contacts?search=<telegramId> (точний пошук за ID працює, коли в запиті лише цифри, від п’яти).

Telegram дозволяє ботам ~30 повідомлень/сек — сервіс сам ставить усе в чергу, твої запити не губляться. На тарифі Free діє ліміт AI-дій — 50 на місяць. Він рахує дії, які Claude робить через MCP; звичайні запити до API з ключем його не витрачають.

Це окрема, зворотна історія: блок «Дії → HTTP-запит» у воронці шле POST на твою адресу з даними контакта в потрібний момент воронки. А «Ретрансляція» в Інтеграціях копіює всі оновлення Telegram на твій URL (до 5 адрес) — для співіснування з іншим сервісом на час переїзду.

POST /api/webinars/<webinarId>/report-sale з Bearer API-ключем.

Тіло: amountCents (обовʼязково, у копійках, більше нуля) + будь-який ключ учасника: participantToken / email / phone / telegramId. Опційно: currency (UAH за замовч.), buttonId, orderId, boardId (дошка CRM; без нього — перша).

Що відбувається: подія webinar_payment у журналі (виторг в аналітиці), CAPI Purchase (якщо ввімкнено галочку на вкладці Інтеграції) і Угода в CRM з джерелом «вебінар/кнопка» (якщо учасник звʼязаний з Персоною).

Учасника не знайдено за жодним ключем — відповідь 404. Успіх — {"ok": true, "participantId": "…", "dealId": "…"}. orderId іде в Meta як ідентифікатор події, щоб та сама покупка не порахувалась там двічі.