AI 聊天机器人

聊天机器人功能允许您创建 AI 驱动的占星助手，可以嵌入到您的网站或通过 API 使用。聊天机器人可以回答关于本命盘、行运的问题，并提供个性化的占星洞察。

概述

AI 驱动：使用先进语言模型进行自然对话
出生数据感知：聊天机器人可访问用户出生数据以提供个性化解读
可嵌入小组件：适用于您网站的即插即用聊天小组件
流式响应：实时 SSE 流以获得即时反馈
插件系统：为每个聊天机器人启用特定占星功能
用量追踪：监控 token 用量和消息数量

创建聊天机器人

bash

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"]
      }
    }
  }'

响应

json

{
  "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"
    }
  }
}

聊天端点

基本聊天

发送不带出生数据上下文的消息：

bash

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
  }'

带出生数据的聊天

发送包含内联出生数据的消息以获取个性化响应：

bash

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"
    }
  }'

带档案的聊天

使用已保存的档案在对话中保持一致的出生数据：

bash

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}}

聊天档案

档案存储用户的出生数据，无需每次重新发送出生数据即可获得个性化响应。

创建档案

bash

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"
        }
      }
    }
  }'

列出档案

bash

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

小组件集成

使用小组件端点在您的网站上嵌入聊天小组件。

INFO

小组件端点使用 /widget/ 路径（不带 /api/ 前缀），并验证 Origin 请求头以进行域名限制。

获取小组件配置

bash

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

小组件聊天

小组件通过 Origin 请求头进行域名验证（浏览器强制执行）：

bash

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 端点。首次使用时会自动创建档案：

bash

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

新用户的第一条消息才需要提供出生数据。后续消息可以省略出生数据。

域名限制

为安全起见，您可以限制哪些域名可以访问您的小组件：

json

{
  "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 查看根据您组织模块可用的插件。

对话历史

获取对话

获取完整的消息历史：

bash

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

删除对话

bash

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

用量追踪

监控您的聊天机器人用量：

bash

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

响应

json

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

管理聊天机器人

列出聊天机器人

bash

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

更新聊天机器人

bash

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"]
      }
    }
  }'

删除聊天机器人

bash

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

错误处理

常见错误响应：

状态码	描述
400	无效请求（缺少字段、验证错误）
401	需要 API 密钥或 API 密钥无效
403	域名不被允许（小组件）或没有活动组织
404	聊天机器人、档案或对话未找到

错误响应示例：

json

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

AI 聊天机器人 ​

概述 ​

创建聊天机器人 ​

响应 ​

聊天端点 ​

基本聊天 ​

带出生数据的聊天 ​

带档案的聊天 ​

流式响应 ​

聊天档案 ​

创建档案 ​

列出档案 ​

小组件集成 ​

获取小组件配置 ​

小组件聊天 ​

带用户档案的小组件 ​

域名限制 ​

可用插件 ​

对话历史 ​

获取对话 ​

删除对话 ​

用量追踪 ​

响应 ​

管理聊天机器人 ​

列出聊天机器人 ​

更新聊天机器人 ​

删除聊天机器人 ​

错误处理 ​

AI 聊天机器人

概述

创建聊天机器人

响应

聊天端点

基本聊天

带出生数据的聊天

带档案的聊天

流式响应

聊天档案

创建档案

列出档案

小组件集成

获取小组件配置

小组件聊天

带用户档案的小组件

域名限制

可用插件

对话历史

获取对话

删除对话

用量追踪

响应

管理聊天机器人

列出聊天机器人

更新聊天机器人

删除聊天机器人

错误处理