Chatbot AI

Tính năng Chatbot cho phép bạn tạo các trợ lý chiêm tinh học được hỗ trợ bởi AI có thể được nhúng vào website của bạn hoặc sử dụng qua API. Chatbot có thể trả lời các câu hỏi về lá số tử vi, quá độ và cung cấp thông tin chiêm tinh học cá nhân hóa.

Tổng quan

• Được hỗ trợ bởi AI: Sử dụng các mô hình ngôn ngữ tiên tiến để trò chuyện tự nhiên
• Nhận biết dữ liệu sinh: Chatbot có thể truy cập dữ liệu sinh của người dùng để đọc cá nhân hóa
• Widget có thể nhúng: Widget trò chuyện drop-in cho website của bạn
• Phản hồi streaming: Streaming SSE thời gian thực để phản hồi tức thì
• Hệ thống plugin: Bật các tính năng chiêm tinh học cụ thể cho từng chatbot
• Theo dõi sử dụng: Giám sát việc sử dụng token và số lượng tin nhắn

Tạo Chatbot

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

Phản hồi

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

Các Endpoint Trò chuyện

Trò chuyện Cơ bản

Gửi tin nhắn không có ngữ cảnh dữ liệu sinh:

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

Trò chuyện với Dữ liệu Sinh

Gửi tin nhắn với dữ liệu sinh nội tuyến để nhận phản hồi cá nhân hóa:

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

Trò chuyện với Hồ sơ

Sử dụng hồ sơ đã lưu để có dữ liệu sinh nhất quán qua các cuộc trò chuyện:

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

Phản hồi Streaming

Tất cả các endpoint trò chuyện trả về Server-Sent Events (SSE) để streaming thời gian thực:

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

Hồ sơ Trò chuyện

Các hồ sơ lưu trữ dữ liệu sinh cho người dùng, cho phép phản hồi cá nhân hóa mà không cần gửi lại dữ liệu sinh mỗi lần.

Tạo Hồ sơ

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

Liệt kê Hồ sơ

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

Tích hợp Widget

Nhúng widget trò chuyện vào website của bạn bằng các endpoint widget.

INFO

Các endpoint widget sử dụng đường dẫn /widget/ (không có tiền tố /api/) và xác thực header Origin để hạn chế tên miền.

Lấy Cấu hình Widget

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

Trò chuyện Widget

Widget sử dụng xác thực tên miền qua header Origin (do trình duyệt thực thi):

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

Widget với Hồ sơ Người dùng

Đối với người dùng quay lại, sử dụng endpoint ID người dùng bên ngoài. Hồ sơ được tạo tự động khi lần đầu sử dụng:

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

Dữ liệu sinh chỉ bắt buộc trong tin nhắn đầu tiên cho người dùng mới. Các tin nhắn tiếp theo có thể bỏ qua nó.

Hạn chế Tên miền

Để bảo mật, bạn có thể hạn chế các tên miền nào có thể truy cập widget của bạn:

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

Nếu allowedDomains trống, tất cả các tên miền đều được phép.

Các Plugin Có sẵn

Plugin xác định các tính năng chiêm tinh học mà chatbot có thể truy cập:

Plugin	Mô tả	Module Bắt buộc
natal	Tính toán và giải thích lá số tử vi	module:natal
transit	Thông tin quá độ hiện tại	module:transit
synastry	Phân tích tương hợp quan hệ	module:synastry
composite	Phân tích lá số kết hợp	module:composite
progressions	Tiến triển thứ cấp	module:progression
solar_return	Lá số hồi quy mặt trời	module:solar-return
lunar_return	Lá số hồi quy mặt trăng	module:lunar-return
retrograde	Thông tin giai đoạn nghịch hành	module:retrograde
numerology	Tính toán số học	module:numerology
compatibility	Tương hợp chiêm tinh học	module:compatibility
chinese_zodiac	Thông tin hoàng đạo Trung Quốc	module:chinese-horoscope
daily_insight	Thông tin chiêm tinh học hàng ngày	module:transit
moon	Dữ liệu pha trăng và lịch mặt trăng	module:moon
daily_horoscope	Nội dung tử vi hàng ngày	module:daily-report

TIP

Sử dụng GET /api/chatbots/plugins để liệt kê tất cả các plugin có sẵn, hoặc GET /api/chatbots/available-plugins để xem các plugin nào có sẵn dựa trên các module của tổ chức bạn.

Lịch sử Cuộc trò chuyện

Lấy Cuộc trò chuyện

Lấy toàn bộ lịch sử tin nhắn:

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

Xóa Cuộc trò chuyện

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

Theo dõi Sử dụng

Giám sát việc sử dụng chatbot của bạn:

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

Phản hồi

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

Quản lý Chatbot

Liệt kê Chatbot

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

Cập nhật Chatbot

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

Xóa Chatbot

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

Xử lý Lỗi

Các phản hồi lỗi phổ biến:

Trạng thái	Mô tả
400	Yêu cầu không hợp lệ (thiếu trường, lỗi xác thực)
401	API key bắt buộc hoặc không hợp lệ
403	Tên miền không được phép (widget) hoặc không có tổ chức đang hoạt động
404	Không tìm thấy chatbot, hồ sơ hoặc cuộc trò chuyện

Ví dụ phản hồi lỗi:

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