Chatbot con IA

La funcionalidad de Chatbot os permite crear asistentes astrológicos impulsados por IA que se pueden incrustar en vuestro sitio web o usar a través de la API. Los chatbots pueden responder preguntas sobre cartas natales, tránsitos y proporcionar perspectivas astrológicas personalizadas.

Descripción General

Impulsado por IA: Usa modelos de lenguaje avanzados para conversaciones naturales
Conciencia de datos de nacimiento: Los chatbots pueden acceder a los datos de nacimiento del usuario para lecturas personalizadas
Widget embebible: Widget de chat listo para usar en vuestro sitio web
Respuestas en streaming: SSE en tiempo real para retroalimentación instantánea
Sistema de plugins: Activad funcionalidades astrológicas específicas por chatbot
Seguimiento de uso: Supervisad el uso de tokens y el recuento de mensajes

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

Respuesta

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

Endpoints de Chat

Chat Básico

Enviad un mensaje sin contexto de datos de nacimiento:

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 con Datos de Nacimiento

Enviad un mensaje con datos de nacimiento en línea para respuestas personalizadas:

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

Usad un perfil guardado para datos de nacimiento consistentes en todas las conversaciones:

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

Respuesta en Streaming

Todos los endpoints de chat devuelven Server-Sent Events (SSE) para streaming en tiempo real:

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

Perfiles de Chat

Los perfiles almacenan datos de nacimiento de los usuarios, permitiendo respuestas personalizadas sin reenviar los datos de nacimiento cada vez.

Crear un Perfil

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

Listar Perfiles

bash

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

Incrustad un widget de chat en vuestro sitio web usando los endpoints del widget.

INFO

Los endpoints del widget usan la ruta /widget/ (sin el prefijo /api/) y validan la cabecera Origin para las restricciones de dominio.

bash

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

El widget usa la validación de dominio a través de la cabecera Origin (aplicada por el navegador):

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

Para usuarios recurrentes, usad el endpoint de ID de usuario externo. El perfil se crea automáticamente en el primer uso:

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

Los datos de nacimiento solo son necesarios en el primer mensaje para un nuevo usuario. Los mensajes posteriores pueden omitirlos.

Restricciones de Dominio

Por seguridad, podéis restringir qué dominios pueden acceder a vuestro widget:

json

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

Si allowedDomains está vacío, se permiten todos los dominios.

Plugins Disponibles

Los plugins determinan a qué funcionalidades astrológicas puede acceder el chatbot:

Plugin	Descripción	Módulo Requerido
`natal`	Cálculos e interpretaciones de carta natal	`module:natal`
`transit`	Información de tránsitos actuales	`module:transit`
`synastry`	Análisis de compatibilidad en relaciones	`module:synastry`
`composite`	Análisis de carta compuesta	`module:composite`
`progressions`	Progresiones secundarias	`module:progression`
`solar_return`	Cartas de retorno solar	`module:solar-return`
`lunar_return`	Cartas de retorno lunar	`module:lunar-return`
`retrograde`	Información sobre períodos retrógrados	`module:retrograde`
`numerology`	Cálculos de numerología	`module:numerology`
`compatibility`	Compatibilidad astrológica	`module:compatibility`
`chinese_zodiac`	Información del zodiaco chino	`module:chinese-horoscope`
`daily_insight`	Perspectivas astrológicas diarias	`module:transit`
`moon`	Datos de fase lunar y calendario lunar	`module:moon`
`daily_horoscope`	Contenido de horóscopo diario	`module:daily-report`

TIP

Usad GET /api/chatbots/plugins para listar todos los plugins disponibles, o GET /api/chatbots/available-plugins para ver qué plugins están disponibles basándose en los módulos de vuestra organización.

Historial de Conversaciones

Obtener Conversación

Recuperad el historial completo de mensajes:

bash

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

Eliminar Conversación

bash

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

Seguimiento de Uso

Supervisad el uso de vuestro chatbot:

bash

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

Respuesta

json

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

Gestión de Chatbots

Listar Chatbots

bash

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

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

Eliminar Chatbot

bash

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

Gestión de Errores

Respuestas de error más comunes:

Estado	Descripción
400	Solicitud no válida (campos faltantes, errores de validación)
401	Clave de API requerida o no válida
403	Dominio no permitido (widget) o sin organización activa
404	Chatbot, perfil o conversación no encontrado

Ejemplo de respuesta de error:

json

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

Chatbot con IA

Descripción General

Crear un Chatbot

Respuesta

Endpoints de Chat

Chat Básico

Chat con Datos de Nacimiento

Chat con Perfil

Respuesta en Streaming

Perfiles de Chat

Crear un Perfil

Listar Perfiles

Integración del Widget

Obtener Configuración del Widget

Chat del Widget

Widget con Perfiles de Usuario

Restricciones de Dominio

Plugins Disponibles

Historial de Conversaciones

Obtener Conversación

Eliminar Conversación

Seguimiento de Uso

Respuesta

Gestión de Chatbots

Listar Chatbots

Actualizar Chatbot

Eliminar Chatbot

Gestión de Errores

Chatbot con IA ​

Descripción General ​

Crear un Chatbot ​

Respuesta ​

Endpoints de Chat ​

Chat Básico ​

Chat con Datos de Nacimiento ​

Chat con Perfil ​

Respuesta en Streaming ​

Perfiles de Chat ​

Crear un Perfil ​

Listar Perfiles ​

Integración del Widget ​

Obtener Configuración del Widget ​

Chat del Widget ​

Widget con Perfiles de Usuario ​

Restricciones de Dominio ​

Plugins Disponibles ​

Historial de Conversaciones ​

Obtener Conversación ​

Eliminar Conversación ​

Seguimiento de Uso ​

Respuesta ​

Gestión de Chatbots ​

Listar Chatbots ​

Actualizar Chatbot ​

Eliminar Chatbot ​

Gestión de Errores ​

Chatbot con IA

Descripción General

Crear un Chatbot

Respuesta

Endpoints de Chat

Chat Básico

Chat con Datos de Nacimiento

Chat con Perfil

Respuesta en Streaming

Perfiles de Chat

Crear un Perfil

Listar Perfiles

Integración del Widget

Obtener Configuración del Widget

Chat del Widget

Widget con Perfiles de Usuario

Restricciones de Dominio

Plugins Disponibles

Historial de Conversaciones

Obtener Conversación

Eliminar Conversación

Seguimiento de Uso

Respuesta

Gestión de Chatbots

Listar Chatbots

Actualizar Chatbot

Eliminar Chatbot

Gestión de Errores