Чат-асистент через API

Останнє оновлення: 2026-10-033 хв читання

Той самий консультант, що працює в кабінеті, доступний з вашого застосунку. Ви створюєте сесію, відкриваєте потік, надсилаєте повідомлення і отримуєте відповідь частинами. Потрібна область tools:chat.

Як це працює

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

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

Сесії

Запит	Що робить
`POST /chat/sessions`	створити сесію
`GET /chat/sessions`	перелік ваших сесій: `limit` 1-50 (за замовчуванням 20, більше - `400`), `cursor`, `q` (пошук у назвах), `projectId`, `archivedOnly`, `sort` (`recent`, `title`)
`PATCH /chat/sessions/{id}`	змінити сесію; хоча б одне поле
`DELETE /chat/sessions/{id}`	прибрати в архів

Тіло POST /chat/sessions (усі поля необов'язкові):

Поле	Опис
`title`	назва сесії, до 200 символів
`projectId`	проєкт, до якого належить сесія
`mode`	`chat_consult` (за замовчуванням); будь-яке інше значення замінюється на `chat_consult`

Поля PATCH /chat/sessions/{id}:

Поле	Опис
`title`	нова назва, до 200 символів
`projectId`	перенести в проєкт; `null` - прибрати з проєкту
`isPinned`	закріпити або відкріпити
`isUnread`	позначити непрочитаною або прочитаною
`isArchived`	тільки `false` - повернути сесію з архіву; в архів - через `DELETE`

curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Питання клієнта про іпотеку"}'

У відповіді є sessionId - його передавайте в усі наступні виклики. Для створення сесії потрібен заповнений профіль акаунта; без нього - 400.

Через API доступний режим загального консультанта. Режим автовідповідача, який працює всередині CRM кабінету, ззовні не вмикається.

Надіслати повідомлення

curl -X POST https://developers.grem.capital/api/v1/chat/messages \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"SESSION_ID","text":"Скільки коштує двокімнатна на Подолі?","clientMessageId":"msg-0001"}'

clientMessageId - обов'язковий ваш ідентифікатор повідомлення. На той самий id відповідають і списують один раз - при повторі передавайте той самий id; це заміна Idempotency-Key для чату.
style (необов'язково) - довжина відповіді: short, normal або detailed.

Відповідь на запит - лише підтвердження прийому; сама відповідь асистента йде потоком.

Потік відповіді

GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream

З'єднання довге, події приходять у міру генерації:

Подія	Що означає
`assistant.started`	асистент почав відповідати
`assistant.delta`	чергова частина тексту в полі `delta`
`assistant.done`	відповідь завершена, повний текст у полі `text`

Якщо з'єднання обірвалося, підключіться знову з тим самим sessionId: сервер переграє поточну відповідь з початку. Тому на assistant.started очищайте накопичений текст цього повідомлення, інакше він задвоїться.

Історія

GET /chat/history?sessionId=SESSION_ID&limit=50 - збережені повідомлення сесії, від старих до нових. limit від 1 до 200 (за замовчуванням 50); наступна сторінка - cursor зі значенням nextCursor з попередньої відповіді. Використовуйте, щоб відновити діалог після перезавантаження інтерфейсу.

Скільки це коштує

Дія	Оплата
`POST /chat/messages`	виклик API + ціна повідомлення
`POST`, `PATCH`, `DELETE` сесій	виклик API
`GET` перелік, історія, потік	безкоштовно

На тарифі Free діє денний ліміт повідомлень. Після нього приходить 429 - продовжіть завтра або змініть тариф. Відповідь містить code: free_daily_limit і Retry-After до 00:00 UTC, коли ліміт оновлюється.

Пов'язані статті

TypeScript SDK - готовий клієнт з підпискою на потік.
Ліміти і оплата
Помилки

Ця стаття була корисною?