AI-чатбот

Функция чатбота позволяет создавать астрологических ассистентов на основе ИИ, которые можно встраивать на ваш сайт или использовать через API. Чатботы могут отвечать на вопросы о натальных картах, транзитах и предоставлять персонализированные астрологические прогнозы.

Обзор

• Основан на ИИ: использует передовые языковые модели для естественного общения
• Учёт данных о рождении: чатботы могут использовать данные о рождении пользователя для персонализированных чтений
• Встраиваемый виджет: готовый виджет чата для вашего сайта
• Потоковые ответы: потоковая передача SSE в реальном времени для мгновенной обратной связи
• Система плагинов: включение определённых астрологических функций для каждого чатбота
• Отслеживание использования: мониторинг использования токенов и количества сообщений

Создание чатбота

curl -X POST "https://api.astroapi.cloud/api/chatbots" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "chatbots",
      "attributes": {
        "name": "My Astrology Bot",
        "description": "Personal astrology assistant",
        "enabledPlugins": ["natal", "transits"],
        "settings": {
          "greeting": "Hello! I can help you understand your birth chart."
        },
        "widgetConfig": {
          "theme": "light",
          "primaryColor": "#6366f1"
        },
        "allowedDomains": ["example.com", "www.example.com"]
      }
    }
  }'

Ответ

{
  "data": {
    "type": "chatbot",
    "id": "cb_abc123",
    "attributes": {
      "name": "My Astrology Bot",
      "description": "Personal astrology assistant",
      "enabledPlugins": ["natal", "transits"],
      "settings": {
        "greeting": "Hello! I can help you understand your birth chart."
      },
      "widgetConfig": {
        "theme": "light",
        "primaryColor": "#6366f1"
      },
      "allowedDomains": ["example.com", "www.example.com"],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Эндпоинты чата

Базовый чат

Отправка сообщения без контекста данных о рождении:

curl -X POST "https://api.astroapi.cloud/api/chat/{chatbotId}" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What does it mean to have Sun in Aries?",
    "conversationId": null
  }'

Чат с данными о рождении

Отправка сообщения с встроенными данными о рождении для персонализированных ответов:

curl -X POST "https://api.astroapi.cloud/api/chat/{chatbotId}/direct" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tell me about my Sun sign",
    "birthData": {
      "date": "1990-06-15",
      "time": "14:30",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "placeName": "London, UK",
      "timezone": "Europe/London"
    }
  }'

Чат с профилем

Использование сохранённого профиля для постоянных данных о рождении в разных разговорах:

curl -X POST "https://api.astroapi.cloud/api/chat/{chatbotId}/profile/{profileId}" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What transits are affecting me this week?",
    "conversationId": "conv_xyz789"
  }'

Потоковый ответ

Все эндпоинты чата возвращают Server-Sent Events (SSE) для потоковой передачи в реальном времени:

event: message
data: {"content": "Based on your birth chart, "}

event: message
data: {"content": "your Sun in Aries suggests..."}

event: done
data: {"conversationId": "conv_xyz789", "usage": {"inputTokens": 150, "outputTokens": 75}}

Профили чата

Профили хранят данные о рождении пользователей, обеспечивая персонализированные ответы без необходимости повторно отправлять данные о рождении.

Создание профиля

curl -X POST "https://api.astroapi.cloud/api/chatbots/{chatbotId}/profiles" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "chat-profile",
      "attributes": {
        "externalUserId": "user_123",
        "birthDate": "1990-06-15",
        "birthTime": "14:30",
        "birthPlaceLat": 51.5074,
        "birthPlaceLng": -0.1278,
        "birthPlaceName": "London, UK",
        "timezone": "Europe/London",
        "metadata": {
          "name": "John Doe"
        }
      }
    }
  }'

Список профилей

curl -X GET "https://api.astroapi.cloud/api/chatbots/{chatbotId}/profiles" \
  -H "X-Api-Key: your-api-key"

Интеграция виджета

Встраивание виджета чата на ваш сайт с помощью эндпоинтов виджета.

INFO

Эндпоинты виджета используют путь /widget/ (без префикса /api/) и проверяют заголовок Origin для ограничений по доменам.

Получение конфигурации виджета

curl -X GET "https://api.astroapi.cloud/widget/config/{chatbotId}"

Чат через виджет

Виджет использует проверку домена через заголовок Origin (применяется браузером):

curl -X POST "https://api.astroapi.cloud/widget/chat/{chatbotId}" \
  -H "X-Api-Key: your-widget-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is my horoscope for today?",
    "birthData": {
      "date": "1990-06-15",
      "time": "14:30",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }'

Виджет с профилями пользователей

Для возвращающихся пользователей используйте эндпоинт внешнего ID пользователя. Профиль создаётся автоматически при первом использовании:

curl -X POST "https://api.astroapi.cloud/widget/chat/{chatbotId}/user/{externalUserId}" \
  -H "X-Api-Key: your-widget-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are my current transits?",
    "birthData": {
      "date": "1990-06-15",
      "time": "14:30",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }'

TIP

Данные о рождении требуются только в первом сообщении нового пользователя. В последующих сообщениях их можно опустить.

Ограничения по доменам

В целях безопасности можно ограничить домены, которые могут обращаться к вашему виджету:

{
  "allowedDomains": ["example.com", "www.example.com", "app.example.com"]
}

Если allowedDomains пуст, разрешены все домены.

Доступные плагины

Плагины определяют, к каким астрологическим функциям чатбот может получать доступ:

Плагин	Описание	Необходимый модуль
natal	Расчёты и интерпретации натальной карты	module:natal
transit	Информация о текущих транзитах	module:transit
synastry	Анализ совместимости отношений	module:synastry
composite	Анализ композитной карты	module:composite
progressions	Вторичные прогрессии	module:progression
solar_return	Карты солярного возврата	module:solar-return
lunar_return	Карты лунного возврата	module:lunar-return
retrograde	Информация о периодах ретроградности	module:retrograde
numerology	Нумерологические расчёты	module:numerology
compatibility	Астрологическая совместимость	module:compatibility
chinese_zodiac	Информация о китайском зодиаке	module:chinese-horoscope
daily_insight	Ежедневные астрологические прозрения	module:transit
moon	Данные о фазе Луны и лунном календаре	module:moon
daily_horoscope	Контент ежедневных гороскопов	module:daily-report

TIP

Используйте GET /api/chatbots/plugins для списка всех доступных плагинов или GET /api/chatbots/available-plugins для просмотра плагинов, доступных на основе модулей вашей организации.

История разговоров

Получение разговора

Получение полной истории сообщений:

curl -X GET "https://api.astroapi.cloud/api/chat/{chatbotId}/conversation/{conversationId}" \
  -H "X-Api-Key: your-api-key"

Удаление разговора

curl -X DELETE "https://api.astroapi.cloud/api/chat/{chatbotId}/conversation/{conversationId}" \
  -H "X-Api-Key: your-api-key"

Отслеживание использования

Мониторинг использования вашего чатбота:

curl -X GET "https://api.astroapi.cloud/api/chatbots/usage" \
  -H "X-Api-Key: your-api-key"

Ответ

{
  "data": {
    "type": "chatbot-usage",
    "id": "org_abc-2024-01",
    "attributes": {
      "month": "2024-01",
      "totalInputTokens": 15000,
      "totalOutputTokens": 45000,
      "totalMessages": 250
    }
  }
}

Управление чатботами

Список чатботов

curl -X GET "https://api.astroapi.cloud/api/chatbots" \
  -H "X-Api-Key: your-api-key"

Обновление чатбота

curl -X PATCH "https://api.astroapi.cloud/api/chatbots/{id}" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "chatbots",
      "attributes": {
        "name": "Updated Bot Name",
        "enabledPlugins": ["natal", "transits", "synastry"]
      }
    }
  }'

Удаление чатбота

curl -X DELETE "https://api.astroapi.cloud/api/chatbots/{id}" \
  -H "X-Api-Key: your-api-key"

Обработка ошибок

Типичные ответы с ошибками:

Статус	Описание
400	Неверный запрос (отсутствующие поля, ошибки валидации)
401	API-ключ обязателен или недействителен
403	Домен не разрешён (виджет) или нет активной организации
404	Чатбот, профиль или разговор не найден

Пример ответа с ошибкой:

{
  "errors": [{
    "status": "403",
    "title": "Domain not allowed"
  }]
}