Для розробника

Ця сторінка — для того, хто вбудовує агента у власний застосунок. Тут описано, коли API взагалі потрібен, які бувають ключі й з чого почати.

Шукаєте перелік ендпоїнтів?

Довідник API → — усі ендпоїнти платформи зі схемами, прикладами й кнопкою «спробувати»: розмова, віджет, агенти, хід, тригери, знання, дії, звернення, команда й тарифікація.

Коли API потрібен, а коли ні

Не потрібен, якщо ви:

ставите агента на сайт готовим вікном — досить коду для сайту;
приймаєте звернення в кабінеті або в Telegram — див. Щоб міг відповісти живий оператор;
наповнюєте знання руками через кабінет.

Потрібен, якщо ви:

робите власний інтерфейс чату — у мобільному застосунку або на своєму сайті;
приймаєте звернення у власній системі підтримки замість кабінету;
синхронізуєте знання агента з каталогом чи базою з вашої системи автоматично;
будите агента подіями зі своєї системи — це вхідний вебхук тригера.

Довідник


Інтерактивний довідник	https://api.youselfbot.com/docs
Машинна специфікація	https://api.youselfbot.com/v1/openapi.json

Довідник описує весь HTTP API, а не лише інтеграційні виклики: кабінет — це просто перший клієнт того самого API, тож усе, що вміє він, доступно й вам. Специфікація за другим посиланням придатна для генерації клієнта.

Ця сторінка пояснює, що там шукати.

Ключі

Кабінет видає агентові кілька ключів: агент → Підключення → блок Ключі.

Ключ	Де береться	Де працює
`pk_…` Публічний	сніпет віджета, блок Ключі	лише віджет у браузері
`sk_…` Серверний	блок Ключі → Створити новий	це API (`/v1/api/`, `/v1/admin/`)
Підтвердження відвідувача	блок Ключі → Створити новий	підпис особи відвідувача на вашому сервері

Публічний ключ для цього API не підходить: будь-який виклик /v1/api/* з pk_-ключем повертає 403 з кодом wrong_key_type — не 401. Ключ дійсний, просто не того типу. Це найчастіша помилка на старті.

Серверний ключ живе тільки на бекенді

Ніколи не показуйте sk_… у браузері, мобільному застосунку чи публічному репозиторії. CORS для /v1/api/* не налаштований саме тому.

Ключ показується один раз

І серверний ключ, і ключ підтвердження відвідувача видно повністю лише в момент видачі — у плашці «Новий серверний ключ — скопіюйте зараз». Після оновлення сторінки лишиться тільки початок. Перевипуск ламає старий ключ негайно: усе, що ним користується, зупиниться, доки ви не пропишете новий.

Hello world

bash

KEY="sk_ваш_серверний_ключ"
BASE="https://api.youselfbot.com"
SESSION=$(uuidgen)   # непередбачуваний id, один на діалог

curl -sS -X POST "$BASE/v1/api/chat" \
  -H "X-Bot-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$SESSION\",\"message\":\"Які у вас години роботи?\"}"
# {"answer":"Ми працюємо з 9:00 до 18:00, пн–пт.","session_id":"…"}

Наступна репліка того самого діалогу — той самий session_id. Так агент пам'ятає контекст.

Розмова

Виклик	Про що
`POST /v1/api/chat`	одна репліка, відповідь повністю
`POST /v1/api/chat/stream`	те саме, але потоком (SSE) — відповідь друкується на очах
`POST /v1/api/visitors/erase`	видалити все, що зберігається про одного відвідувача

Відповідь 200 на chat має три режими, і всі приходять із тим самим статусом: звичайна відповідь, "handoff": true (розмову веде людина) і "quota_exceeded": true (вичерпано ліміт). Перевіряйте прапорці явно.

Порожній answer не показуйте як репліку

Коли розмову веде людина, answer може бути порожнім: репліку просто переслано оператору. Це найчастіша помилка при першій інтеграції — у чаті з'являються порожні бульбашки від бота.

Передача людині

Виклик	Про що
`POST /v1/api/handoff`	клієнт просить оператора
`GET /v1/api/messages`	забрати нові повідомлення оператора
`POST /v1/api/typing`	«клієнт друкує…» для ваших операторів
`GET /v1/api/operator/threads`	список звернень
`GET /v1/api/operator/threads/{sid}`	повний транскрипт
`POST /v1/api/operator/threads/{sid}/reply`	відповідь оператора
`POST /v1/api/operator/threads/{sid}/typing`	«оператор друкує…»
`POST /v1/api/operator/threads/{sid}/resolve`	завершити звернення

bash

KEY="sk_ваш_серверний_ключ"
BASE="https://api.youselfbot.com"
SID="3f6c1b9e-7f42-4d2a-9a6f-0d5b1f0b21c7"

# Прочитати транскрипт звернення
curl -sS "$BASE/v1/api/operator/threads/$SID" -H "X-Bot-Key: $KEY"

# Відповісти клієнту
curl -sS -X POST "$BASE/v1/api/operator/threads/$SID/reply" \
  -H "X-Bot-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Вітаю! Перевіряю ваше замовлення, хвилинку."}'

# Показати клієнту «оператор друкує…»
curl -sS -X POST "$BASE/v1/api/operator/threads/$SID/typing" -H "X-Bot-Key: $KEY"

# Завершити — далі знову відповідає агент
curl -sS -X POST "$BASE/v1/api/operator/threads/$SID/resolve" -H "X-Bot-Key: $KEY"

Відповідь оператора доходить до відвідувача так само, як відповідь із кабінету, — у реальному часі. Ваша система й кабінет можуть працювати одночасно.

Разом із вихідними вебхуками це дає повний цикл без полінгу. GET /v1/api/operator/threads корисний для початкової синхронізації або відновлення після простою.

Клієнтський бік: свій чат

Якщо у вас власний інтерфейс чату замість нашого вікна:

bash

# Клієнт просить оператора
curl -sS -X POST "$BASE/v1/api/handoff" \
  -H "X-Bot-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$SID\"}"
# {"status":"waiting"}

# Забрати нові повідомлення оператора
curl -sS "$BASE/v1/api/messages?session_id=$SID&after=0" -H "X-Bot-Key: $KEY"

json

{
  "messages": [
    { "id": "msg_…", "author": "operator", "text": "Вітаю!", "at": 1753600000123 }
  ],
  "status": "operator",
  "operator_typing": false,
  "next_cursor": "…"
}

after — значення at останнього отриманого повідомлення. Перший запит — 0.
next_cursor точніший за after: він розрізняє повідомлення, надіслані в ту саму мілісекунду. Якщо він є — використовуйте ?cursor=.
operator_typing згасає сам приблизно через 6 секунд, тож просто перемальовуйте індикатор за значенням із кожного опитування.

Знання

Виклик	Про що
`POST /v1/api/knowledge`	навчити агента документом
`GET /v1/api/knowledge`	перелічити джерела (з пагінацією)
`GET /v1/api/knowledge/{id}`	прочитати джерело повністю
`DELETE /v1/api/knowledge/{id}`	видалити джерело

bash

curl -sS -X POST "$BASE/v1/api/knowledge" \
  -H "X-Bot-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
        "source_id": "catalog-item-4417",
        "title": "Лампа Nord 40W",
        "text": "Лампа Nord 40W. Ціна 1290 грн. Гарантія 24 місяці…"
      }'

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

Усе, що додано так, видно в кабінеті в розділі Знання — і навпаки.

Що треба знати заздалегідь

Ідемпотентність

Кожен виклик із побічним ефектом приймає заголовок Idempotency-Key. Повтор після таймауту не виконає дію вдруге — повернеться збережена відповідь першої спроби із заголовком Idempotency-Replayed: true. Ключ живе 24 години.

Це не опція «про всяк випадок»: без нього мережевий таймаут на POST .../reply може надіслати клієнту друге таке саме повідомлення.

Помилки

Кожна помилка — JSON із двома полями:

json

{ "error": "wrong key type: this endpoint needs a secret key (sk_)", "code": "wrong_key_type" }

Розгалужуйтесь на code, не на error: текст може змінитися будь-коли. Перелік кодів поповнюється — незнайомий код обробляйте як загальну помилку відповідного HTTP-статусу, а не падайте.

Ліміти запитів

60 запитів за хвилину на діалог і записи, 240 — на читання та сигнали. Вікно — одна хвилина, окремо на пару «ключ + IP».

Заголовки RateLimit-Limit, RateLimit-Remaining і RateLimit-Reset є на кожній відповіді, не лише на 429.

Версіонування

Префікс /v1 фіксує контракт. У його межах зміни лише адитивні: нові виклики, нові поля у відповідях, нові необов'язкові поля в запитах, нові значення code. Наявні поля не перейменовуються, не змінюють тип і не зникають.

Тому ваш клієнт мусить ігнорувати незнайомі поля й толерувати незнайомі значення переліків. Несумісна зміна = новий префікс, який працює паралельно.

Ідентифікатор запиту

Кожна відповідь містить X-Request-Id. Збережіть його у своїх логах — зі зверненням у підтримку він одразу вказує на потрібний запис у наших. Можна надіслати свій — тоді один ідентифікатор пройде наскрізь через ваші системи й наші.

Чого тут немає

Конструювання агента — хід і кроки, тригери, журнал запусків, стан, готові набори — живе в кабінеті й не є публічним контрактом: воно змінюється разом з інтерфейсом.

Публічне й стабільне — рівно те, що перелічено вище: /v1/api/*, /v1/admin/*, вхідний вебхук тригера й вихідні вебхуки.

Далі

Вебхуки — події від нас до вас і сигнал від вас до агента.

Для розробника ​

Коли API потрібен, а коли ні ​

Довідник ​

Ключі ​

Hello world ​

Розмова ​

Передача людині ​

Клієнтський бік: свій чат ​

Знання ​

Що треба знати заздалегідь ​

Ідемпотентність ​

Помилки ​

Ліміти запитів ​

Версіонування ​

Ідентифікатор запиту ​

Чого тут немає ​

Далі ​

Для розробника

Коли API потрібен, а коли ні

Довідник

Ключі

Hello world

Розмова

Передача людині

Клієнтський бік: свій чат

Знання

Що треба знати заздалегідь

Ідемпотентність

Помилки

Ліміти запитів

Версіонування

Ідентифікатор запиту

Чого тут немає

Далі