Guides

Integrate Astro Chat into your app

Astro Chat turns a saved birth profile into a personalized Kundli, Western, or compatibility conversation. Your product sends a question, receives an answer, and keeps the returned session ID for follow-ups.

Choose the conversation type

New accounts receive test credits. The token belongs in an environment variable such as ASTROLOGYAPI_TOKEN, and your server adds it as the x-astrologyapi-keyheader. A browser, mobile bundle, or public repository is never a safe place for this token.

How the flow works

1. Collect or load a saved birth profile.
2. Send the profile and question from your backend to the Chat API.
3. Store the returned sid against the user's chat session.
4. Send the same sid on the next question to continue the conversation.

Step 1: make your first request

All chat types use POST https://json-chat.astrologyapi.com/api/chat. For a personalized chart conversation, set ap to KUNDLI, then choose VEDIC or WESTERN with ac.

curl --location 'https://json-chat.astrologyapi.com/api/chat' \
  --header 'Content-Type: application/json' \
  --header 'x-astrologyapi-key: <YOUR_ACCESS_TOKEN>' \
  --data '{
    "language": "en",
    "name": "David",
    "day": 1,
    "month": 11,
    "year": 2005,
    "hour": 19,
    "min": 45,
    "place": "Mumbai",
    "lat": "19.17",
    "lon": "73.7",
    "tzone": "5.5",
    "gender": "male",
    "country": "INDIA",
    "ap": "KUNDLI",
    "ac": "VEDIC",
    "ep": "STANDARD",
    "sid": "",
    "q": "What does my Moon sign say about me?"
  }'

Read the response

Render message as the assistant reply. Saveresponse.sid; it is the server-issued key that carries the conversation forward.

{
  "status": true,
  "message": "Based on your birth details, your Sun is in Scorpio...",
  "response": {
    "sid": "astro-6",
    "timestamp": "2026-01-28T12:00:00Z"
  }
}

Step 2: persist the session ID

The response contains the answer in message and a conversation ID in response.sid. Persist that value with the selected profile and send it with every follow-up question. Create a new session when the user changes profile or starts a new topic.

1. First question: send an empty sid.
2. Save the returned ID with the selected user and profile.
3. Follow-up: send the exact same ID with the new q.
4. New person or deliberately fresh chat: discard the old ID and start empty.

Step 3: call the API from your backend

Your frontend should call your own route, which validates the request and forwards it with the server-held token. This compact Node 18+ example returns only the response fields your chat UI needs.

// Node 18+ route handler. Keep the token on your server.
const CHAT_URL = 'https://json-chat.astrologyapi.com/api/chat'

export async function askAstroChat({ question, sid = '', profile }) {
  const response = await fetch(CHAT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-astrologyapi-key': process.env.ASTROLOGYAPI_TOKEN,
    },
    body: JSON.stringify({
      ...profile,
      ap: 'KUNDLI',
      ac: 'VEDIC',
      ep: 'STANDARD',
      sid,
      q: question,
    }),
  })

  const data = await response.json()
  if (!response.ok || !data.status) throw new Error('Chat service unavailable')

  return { reply: data.message, sid: data.response.sid }
}

Connect the frontend

Keep the session ID in client state while the chat is open. Your backend should still own the token and the final profile validation.

let sid = null

async function sendMessage(question, profile) {
  const response = await fetch('/api/astro-chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ question, sid, profile }),
  })

  const data = await response.json()
  if (!response.ok) throw new Error(data.error || 'Chat failed')

  sid = data.sid // send this on the next message
  return data.reply
}

Step 4: add compatibility chat

For relationship questions, set ap to MATCHING and send both birth profiles using the f_ and m_ fields. The same session-ID pattern applies.

Do not turn two individual readings into a scientific compatibility score. Use the conversation to explain similarities, contrasts, and traditional relationship themes with clear entertainment-oriented framing.

{
  "ap": "MATCHING",
  "sid": "",
  "q": "What should we understand about this relationship?",
  "f_first_name": "Asha",
  "f_day": 10,
  "f_month": 5,
  "f_year": 1994,
  "f_hour": 9,
  "f_minute": 30,
  "f_latitude": 19.07,
  "f_longitude": 72.88,
  "f_timezone": 5.5,
  "f_place": "Mumbai",
  "m_first_name": "Rohan",
  "m_day": 3,
  "m_month": 8,
  "m_year": 1992,
  "m_hour": 18,
  "m_minute": 15,
  "m_latitude": 28.61,
  "m_longitude": 77.21,
  "m_timezone": 5.5,
  "m_place": "Delhi"
}

Handle production cases

• Missing or invalid token: return a friendly authentication message; never expose the token or upstream response body.
• Invalid birth details: validate every required field before calling the API and keep the user's draft intact for correction.
• Upstream failure: check both the HTTP status and status in the response body before displaying a reply.
• Wallet protection: rate-limit per user and record each call, especially before opening chat to anonymous traffic.
• Privacy: explain why birth data is collected, who can access it, and how a user can delete a saved profile.

Get birth data right

An incorrect timezone changes the computed chart behind the conversation. Resolve the place into coordinates and the correct decimal offset instead of asking users to type them. Follow the birth time and timezone guide for the required handling of DST and historical birth dates.

Where to go next

• Astro Chat API documentation for the complete parameter list and all conversation types.
• Credits, errors, and going to production before you point real traffic at your backend.
• Ground an LLM on computed charts when you want to pair calculated data with your own AI experience.