Chatbot com IA

A funcionalidade Chatbot permite-te criar assistentes de astrologia com IA que podem ser integrados no teu site ou usados via API. Os chatbots podem responder a perguntas sobre mapas natais, trânsitos e fornecer insights astrológicos personalizados.

Visão Geral

Com IA: Usa modelos de linguagem avançados para conversação natural
Consciente dos dados de nascimento: Os chatbots podem aceder aos dados de nascimento do utilizador para leituras personalizadas
Widget embutível: Widget de chat plug-and-play para o teu site
Respostas em streaming: Streaming SSE em tempo real para feedback instantâneo
Sistema de plugins: Activa funcionalidades astrológicas específicas por chatbot
Acompanhamento de utilização: Monitoriza o uso de tokens e contagens de mensagens

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

Resposta

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

Envia uma mensagem sem contexto de dados de nascimento:

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 com Dados de Nascimento

Envia uma mensagem com dados de nascimento integrados para respostas 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 com Perfil

Usa um perfil guardado para dados de nascimento consistentes entre conversas:

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

Resposta em Streaming

Todos os endpoints de chat devolvem Server-Sent Events (SSE) para streaming em tempo 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}}

Perfis de Chat

Os perfis guardam dados de nascimento dos utilizadores, permitindo respostas personalizadas sem reenviar os dados de nascimento a cada vez.

Criar um 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 Perfis

bash

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

Incorpora um widget de chat no teu site usando os endpoints de widget.

INFO

Os endpoints de widget usam o caminho /widget/ (sem o prefixo /api/) e validam o cabeçalho Origin para restrições de domínio.

bash

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

O widget usa validação de domínio via o cabeçalho Origin (aplicado pelo browser):

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 utilizadores recorrentes, usa o endpoint de ID de utilizador externo. O perfil é criado automaticamente na primeira utilização:

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

Os dados de nascimento só são necessários na primeira mensagem de um novo utilizador. As mensagens subsequentes podem omiti-los.

Restrições de Domínio

Por segurança, podes restringir quais os domínios que podem aceder ao teu widget:

json

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

Se allowedDomains estiver vazio, todos os domínios são permitidos.

Plugins Disponíveis

Os plugins determinam a que funcionalidades astrológicas o chatbot pode aceder:

Plugin	Descrição	Módulo Necessário
`natal`	Cálculos e interpretações de mapa natal	`module:natal`
`transit`	Informação de trânsitos actuais	`module:transit`
`synastry`	Análise de compatibilidade de relacionamentos	`module:synastry`
`composite`	Análise de mapa composto	`module:composite`
`progressions`	Progressões secundárias	`module:progression`
`solar_return`	Mapas de revolução solar	`module:solar-return`
`lunar_return`	Mapas de revolução lunar	`module:lunar-return`
`retrograde`	Informação sobre períodos de retrogradação	`module:retrograde`
`numerology`	Cálculos de numerologia	`module:numerology`
`compatibility`	Compatibilidade astrológica	`module:compatibility`
`chinese_zodiac`	Informação de zodíaco chinês	`module:chinese-horoscope`
`daily_insight`	Insights astrológicos diários	`module:transit`
`moon`	Dados de fase lunar e calendário lunar	`module:moon`
`daily_horoscope`	Conteúdo de horóscopo diário	`module:daily-report`

TIP

Usa GET /api/chatbots/plugins para listar todos os plugins disponíveis, ou GET /api/chatbots/available-plugins para ver quais os plugins disponíveis com base nos módulos da tua organização.

Histórico de Conversas

Obter Conversa

Obtém o histórico completo de mensagens:

bash

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

Eliminar Conversa

bash

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

Acompanhamento de Utilização

Monitoriza a utilização do teu chatbot:

bash

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

Resposta

json

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

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

Tratamento de Erros

Respostas de erro comuns:

Estado	Descrição
400	Pedido inválido (campos em falta, erros de validação)
401	Chave de API necessária ou inválida
403	Domínio não permitido (widget) ou sem organização activa
404	Chatbot, perfil ou conversa não encontrado

Exemplo de resposta de erro:

json

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

Chatbot com IA

Visão Geral

Criar um Chatbot

Resposta

Endpoints de Chat

Chat Básico

Chat com Dados de Nascimento

Chat com Perfil

Resposta em Streaming

Perfis de Chat

Criar um Perfil

Listar Perfis

Integração de Widget

Obter Configuração do Widget

Chat do Widget

Widget com Perfis de Utilizador

Restrições de Domínio

Plugins Disponíveis

Histórico de Conversas

Obter Conversa

Eliminar Conversa

Acompanhamento de Utilização

Resposta

Gerir Chatbots

Listar Chatbots

Actualizar Chatbot

Eliminar Chatbot

Tratamento de Erros

Chatbot com IA ​

Visão Geral ​

Criar um Chatbot ​

Resposta ​

Endpoints de Chat ​

Chat Básico ​

Chat com Dados de Nascimento ​

Chat com Perfil ​

Resposta em Streaming ​

Perfis de Chat ​

Criar um Perfil ​

Listar Perfis ​

Integração de Widget ​

Obter Configuração do Widget ​

Chat do Widget ​

Widget com Perfis de Utilizador ​

Restrições de Domínio ​

Plugins Disponíveis ​

Histórico de Conversas ​

Obter Conversa ​

Eliminar Conversa ​

Acompanhamento de Utilização ​

Resposta ​

Gerir Chatbots ​

Listar Chatbots ​

Actualizar Chatbot ​

Eliminar Chatbot ​

Tratamento de Erros ​

Chatbot com IA

Visão Geral

Criar um Chatbot

Resposta

Endpoints de Chat

Chat Básico

Chat com Dados de Nascimento

Chat com Perfil

Resposta em Streaming

Perfis de Chat

Criar um Perfil

Listar Perfis

Integração de Widget

Obter Configuração do Widget

Chat do Widget

Widget com Perfis de Utilizador

Restrições de Domínio

Plugins Disponíveis

Histórico de Conversas

Obter Conversa

Eliminar Conversa

Acompanhamento de Utilização

Resposta

Gerir Chatbots

Listar Chatbots

Actualizar Chatbot

Eliminar Chatbot

Tratamento de Erros