Chatbot con IA

La funzionalità Chatbot ti consente di creare assistenti astrologici alimentati dall'IA che possono essere incorporati nel tuo sito web o utilizzati tramite API. I chatbot possono rispondere a domande sui temi natali, i transiti e fornire intuizioni astrologiche personalizzate.

Panoramica

• Alimentato dall'IA: Utilizza modelli linguistici avanzati per conversazioni naturali
• Consapevole dei dati di nascita: I chatbot possono accedere ai dati di nascita dell'utente per letture personalizzate
• Widget incorporabile: Widget di chat drop-in per il tuo sito web
• Risposte in streaming: Streaming SSE in tempo reale per feedback istantaneo
• Sistema di plugin: Abilita funzionalità astrologiche specifiche per chatbot
• Monitoraggio dell'utilizzo: Monitora l'utilizzo dei token e il conteggio dei messaggi

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

Risposta

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

Endpoint di Chat

Chat di Base

Invia un messaggio senza contesto dei dati di nascita:

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 con Dati di Nascita

Invia un messaggio con dati di nascita inline per risposte personalizzate:

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 con Profilo

Usa un profilo salvato per dati di nascita coerenti tra le conversazioni:

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

Risposta in Streaming

Tutti gli endpoint di chat restituiscono Server-Sent Events (SSE) per lo streaming in tempo reale:

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

Profili di Chat

I profili memorizzano i dati di nascita degli utenti, abilitando risposte personalizzate senza dover reinviare i dati di nascita ogni volta.

Crea un Profilo

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

Elenca i Profili

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

Integrazione del Widget

Incorpora un widget di chat nel tuo sito web usando gli endpoint del widget.

INFO

Gli endpoint del widget usano il percorso /widget/ (senza il prefisso /api/) e validano l'intestazione Origin per le restrizioni di dominio.

Ottieni la Configurazione del Widget

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

Chat del Widget

Il widget usa la validazione del dominio tramite l'intestazione Origin (applicata dal browser):

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 con Profili Utente

Per gli utenti di ritorno, usa l'endpoint con ID utente esterno. Il profilo viene creato automaticamente al primo utilizzo:

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

I dati di nascita sono richiesti solo nel primo messaggio per un nuovo utente. I messaggi successivi possono ometterli.

Restrizioni di Dominio

Per sicurezza, puoi limitare i domini che possono accedere al tuo widget:

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

Se allowedDomains è vuoto, tutti i domini sono consentiti.

Plugin Disponibili

I plugin determinano le funzionalità astrologiche a cui il chatbot può accedere:

Plugin	Descrizione	Modulo Richiesto
natal	Calcoli e interpretazioni del tema natale	module:natal
transit	Informazioni sui transiti attuali	module:transit
synastry	Analisi della compatibilità relazionale	module:synastry
composite	Analisi del tema composito	module:composite
progressions	Progressioni secondarie	module:progression
solar_return	Temi di rivoluzione solare	module:solar-return
lunar_return	Temi di rivoluzione lunare	module:lunar-return
retrograde	Informazioni sui periodi di retrogradazione	module:retrograde
numerology	Calcoli numerologici	module:numerology
compatibility	Compatibilità astrologica	module:compatibility
chinese_zodiac	Informazioni sullo zodiaco cinese	module:chinese-horoscope
daily_insight	Intuizioni astrologiche giornaliere	module:transit
moon	Dati sulla fase lunare e il calendario	module:moon
daily_horoscope	Contenuto dell'oroscopo giornaliero	module:daily-report

TIP

Usa GET /api/chatbots/plugins per elencare tutti i plugin disponibili, o GET /api/chatbots/available-plugins per vedere quali plugin sono disponibili in base ai moduli della tua organizzazione.

Cronologia delle Conversazioni

Ottieni una Conversazione

Recupera l'intera cronologia dei messaggi:

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

Elimina una Conversazione

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

Monitoraggio dell'Utilizzo

Monitora l'utilizzo del tuo chatbot:

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

Risposta

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

Gestione dei Chatbot

Elenca i Chatbot

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

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

Elimina un Chatbot

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

Gestione degli Errori

Risposte di errore comuni:

Stato	Descrizione
400	Richiesta non valida (campi mancanti, errori di validazione)
401	Chiave API richiesta o non valida
403	Dominio non consentito (widget) o nessuna organizzazione attiva
404	Chatbot, profilo o conversazione non trovati

Esempio di risposta di errore:

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