AI Chatbot

The Chatbot feature allows you to create AI-powered astrology assistants that can be embedded in your website or used via API. Chatbots can answer questions about natal charts, transits, and provide personalized astrological insights.

Overview

AI-powered: Uses advanced language models for natural conversation
Birth data aware: Chatbots can access user birth data for personalized readings
Embeddable widget: Drop-in chat widget for your website
Streaming responses: Real-time SSE streaming for instant feedback
Plugin system: Enable specific astrology features per chatbot
Usage tracking: Monitor token usage and message counts

Creating a Chatbot

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

Response

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

Chat Endpoints

Basic Chat

Send a message without birth data context:

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

Chat with Birth Data

Send a message with inline birth data for personalized responses:

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

Chat with Profile

Use a saved profile for consistent birth data across conversations:

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

Streaming Response

All chat endpoints return Server-Sent Events (SSE) for real-time streaming:

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

Chat Profiles

Profiles store birth data for users, enabling personalized responses without resending birth data each time.

Create a Profile

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

List Profiles

bash

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

Embed a chat widget on your website using the widget endpoints.

bash

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

The widget uses a simplified authentication flow with domain validation:

bash

curl -X POST "https://api.astroapi.cloud/api/widget/chat/{chatbotId}" \
  -H "X-API-Key: your-widget-api-key" \
  -H "X-Widget-Domain: example.com" \
  -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"
    }
  }'

For returning users, use the external user ID endpoint. The profile is created automatically on first use:

bash

curl -X POST "https://api.astroapi.cloud/api/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

Birth data is only required on the first message for a new user. Subsequent messages can omit it.

Domain Restrictions

For security, you can restrict which domains can access your widget:

json

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

If allowedDomains is empty, all domains are allowed.

Available Plugins

Plugins determine what astrological features the chatbot can access:

Plugin	Description
`natal`	Natal chart calculations and interpretations
`transits`	Current transit information
`synastry`	Relationship compatibility analysis
`horoscopes`	Daily/weekly horoscope content

Conversation History

Get Conversation

Retrieve the full message history:

bash

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

Delete Conversation

bash

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

Usage Tracking

Monitor your chatbot usage:

bash

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

Response

json

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

Managing Chatbots

List Chatbots

bash

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

Update Chatbot

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

Delete Chatbot

bash

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

Error Handling

Common error responses:

Status	Description
400	Invalid request (missing fields, validation errors)
401	API key required or invalid
403	Domain not allowed (widget) or no active organization
404	Chatbot, profile, or conversation not found

Example error response:

json

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

AI Chatbot

Overview

Creating a Chatbot

Response

Chat Endpoints

Basic Chat

Chat with Birth Data

Chat with Profile

Streaming Response

Chat Profiles

Create a Profile

List Profiles

Widget Integration

Get Widget Configuration

Widget Chat

Widget with User Profiles

Domain Restrictions

Available Plugins

Conversation History

Get Conversation

Delete Conversation

Usage Tracking

Response

Managing Chatbots

List Chatbots

Update Chatbot

Delete Chatbot

Error Handling

AI Chatbot ​

Overview ​

Creating a Chatbot ​

Response ​

Chat Endpoints ​

Basic Chat ​

Chat with Birth Data ​

Chat with Profile ​

Streaming Response ​

Chat Profiles ​

Create a Profile ​

List Profiles ​

Widget Integration ​

Get Widget Configuration ​

Widget Chat ​

Widget with User Profiles ​

Domain Restrictions ​

Available Plugins ​

Conversation History ​

Get Conversation ​

Delete Conversation ​

Usage Tracking ​

Response ​

Managing Chatbots ​

List Chatbots ​

Update Chatbot ​

Delete Chatbot ​

Error Handling ​

AI Chatbot

Overview

Creating a Chatbot

Response

Chat Endpoints

Basic Chat

Chat with Birth Data

Chat with Profile

Streaming Response

Chat Profiles

Create a Profile

List Profiles

Widget Integration

Get Widget Configuration

Widget Chat

Widget with User Profiles

Domain Restrictions

Available Plugins

Conversation History

Get Conversation

Delete Conversation

Usage Tracking

Response

Managing Chatbots

List Chatbots

Update Chatbot

Delete Chatbot

Error Handling