Чат-ассистент через 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 - готовый клиент с подпиской на поток.
Лимиты и оплата
Ошибки

Эта статья была полезной?