Стартовые подсказки

Получите персональные кнопки для welcome-экрана до первого сообщения покупателя. API выбирает пять подсказок из подготовленного набора секции с учётом страницы, времени и доступных сведений о покупателе. Если в секции отключена память между диалогами, прошлые разговоры для подбора не используются.

Подключение и набор подсказок согласуйте с командой Gravity Field. Вызов этого метода и отображение кнопок реализует ваш клиентский канал; готовый Web-виджет не подключает метод автоматически. Подсказки после ответа ассистента приходят отдельно — в response.ui.suggests метода генерации.

Запрос

POST /shopping/starter-prompts

Метод требует Authorization: Bearer gst_.... Сначала получите или используйте сохранённый гостевой токен. Секцию и пользователя сервер определяет по токену. Статический API-ключ его не заменяет.

Переменная GUEST_ACCESS_TOKEN в примере содержит полный токен сохранённой гостевой сессии:

curl --request POST \
  --url 'https://shopping-assistant-api.gravityfield.ai/shopping/starter-prompts' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $GUEST_ACCESS_TOKEN" \
  --data '{
    "ctx": {
      "type": "CATEGORY",
      "data": ["Сыры"],
      "lng": "10"
    }
  }'

Передавайте актуальный контекст страницы API V2, согласованный с /visit и /choose. Категория и код зоны обслуживания в примере условные; замените их значениями вашей интеграции.

Дополнительные поля внутри ctx допускаются. Сериализованный объект ctx не должен превышать 32 000 символов. На верхнем уровне разрешён только ctx: не передавайте tenant_id, tenantId, resourceId, threadId, messages или runtimeContext.

Запрос не создаёт диалог и не отправляет сообщение ассистенту. Для его выполнения не нужен threadId. История для подбора ограничена текущей гостевой сессией: сессии одного UID не объединяются.

Ответ

При успешном подборе API возвращает 200 OK и ровно пять уникальных подсказок. Ниже пример формы ответа; тексты и порядок зависят от набора секции и контекста:

{
  "enabled": true,
  "selectionId": "7a7726c4-6ff9-4efc-b892-21378916c84e",
  "promptSetVersion": 4,
  "prompts": [
    { "id": "home_by_list", "text": "Подбери товары по моему списку" },
    { "id": "weekly_basket", "text": "Подбери продукты на неделю" },
    { "id": "dinner_recipe", "text": "Что приготовить на ужин" },
    { "id": "breakfast", "text": "Что взять на завтрак" },
    { "id": "cleaning", "text": "Товары для уборки" }
  ]
}

Если набор для секции не включён, ответ содержит только:

{ "enabled": false }

Если набор включён, но подбор не выполнен, например из-за таймаута или ошибки модели, API также возвращает 200 OK:

{
  "enabled": true,
  "selectionId": "7a7726c4-6ff9-4efc-b892-21378916c84e",
  "promptSetVersion": 4,
  "prompts": []
}

Сервер не подставляет резервные подсказки. Причина недоступности, оценки уместности, память покупателя и история в публичный ответ не входят. Ошибки авторизации и неверный запрос возвращаются отдельными HTTP-ошибками, а не пустым успешным ответом.

Ответы используют Cache-Control: no-store. Не помещайте персональные подсказки в общий или публичный кеш.

Отображение и нажатие

1. При открытии welcome-экрана вызовите метод с сохранённым гостевым токеном и актуальным ctx.
2. При enabled: true и непустом prompts покажите пять кнопок в порядке ответа. При enabled: false, пустом массиве или сетевой ошибке используйте собственные статические подсказки из вариации кампании или настроек UI. Обрабатывайте ошибки токена по правилам восстановления сессии.
3. При смене страницы или гостевой сессии отмените прежний запрос либо игнорируйте его поздний ответ, чтобы не показать подсказки из старого контекста.
4. После нажатия отправьте выбранный text как обычное новое сообщение в POST /shopping/generate с тем же гостевым токеном, внешним resourceId и актуальным на момент нажатия контекстом. Для нового разговора создайте threadId; для продолжения сохраните существующий.

Пример тела генерации после нажатия первой кнопки. Замените demo-section и USER_UID значениями сохранённой сессии, создайте свои ID диалога и сообщения:

{
  "threadId": "thread-8f2b1c",
  "resourceId": "USER_UID",
  "messages": [
    {
      "id": "message-1001",
      "role": "user",
      "content": "Подбери товары по моему списку"
    }
  ],
  "runtimeContext": {
    "tenant_id": "demo-section",
    "ctx": { "type": "CATEGORY", "data": ["Сыры"], "lng": "10" }
  }
}

Не добавляйте selectionId, promptSetVersion или ID подсказки в тело генерации. События диалога передавайте по общим правилам трекинга; сам факт подбора не означает показ кнопок или нажатие.

Ошибки и ограничения

CORS допускает заголовок Authorization; запросы OPTIONS не требуют токена. Ошибка подбора не должна мешать покупателю написать сообщение вручную или выбрать статическую подсказку.