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
| Experience | Profile | When to use it |
|---|---|---|
| Kundli Chat | ap: KUNDLI, ac: VEDIC | A personalized Vedic conversation for one person. |
| Western Chat | ap: KUNDLI, ac: WESTERN | A personalized Western astrology conversation for one person. |
| Compatibility Chat | ap: MATCHING | A relationship conversation using two birth profiles. |
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
- Collect or load a saved birth profile.
- Send the profile and question from your backend to the Chat API.
- Store the returned
sidagainst the user's chat session. - Send the same
sidon 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 response as the assistant reply. Savesession_id; it is the server-issued key that carries the conversation forward.
{
"success": true,
"session_id": "5ec38d54-6f24-4efc-b8ba-30b36cdd6591",
"message_id": 1,
"query": "What does my Moon sign say about me?",
"response": "Based on your birth details, your Sun is in Scorpio..."
}| Field | Purpose |
|---|---|
q | The user's question. |
language | The response language code, such as en. |
name, gender, country | The person's basic details for a one-person conversation. |
day, month, year, hour, min | Birth date and time. Use the 24-hour clock for hour. |
sid | Empty for the first message; reuse the returned value afterward. |
ep | Expertise level: STANDARD, ADVANCED, ULTRA_FAST or EXPERT. |
lat, lon, tzone | The birth location and decimal timezone offset. |
Step 2: persist the session ID
The response contains the answer in response and a conversation ID in session_id. 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. For specialist chat, save the selected ap with the session and start a new session when switching personas.
- First question: send an empty
sid. - Save the returned ID with the selected user and profile.
- Follow-up: send the exact same ID with the new
q. - 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.success) throw new Error('Chat service unavailable')
return { reply: data.response, sid: data.session_id }
}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 = ''
async function sendMessage(question, profile) {
const response = await fetch('/api/my-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"
}Specialist personas — One chart. Twelve experts.
Pick a focused astrologer for your user's question. Each persona reads only the parts of the Vedic chart that matter for its topic and answers with chart evidence and a date window.
These are 12 new values for ap. The endpoint, access-token authentication, pd birth-profile structure and response format stay the same.
ap | Title | Covers |
|---|---|---|
CAREER | Career & Employment | Best-fit work, job change, promotion, career timing |
WEALTH | Wealth & Money | Income sources, savings, dhana yogas, money timing |
LOVE | Love & Dating | Attraction patterns, partner needs, compatibility |
MARRIAGE | Marriage | Marriage timing, spouse nature, Manglik, Ashtakoot match |
EDUCATION | Education & Studies | Learning style, subject fit, higher / foreign study |
REMEDIES | Remedies & Doshas | Active doshas, gemstones, Lal Kitab and Vedic remedies |
PERSONALITY | Personality | Strengths, blind spots, how others see you |
CREATIVITY | Creativity | Creative medium, blocks, creativity as income |
EMOTIONAL | Emotional Patterns | Moon-based emotional nature, today's mood |
PAST_LIFE | Past Life & Karma | Symbolic reading of Ketu, 12th house, D60 |
SPIRITUALITY | Spirituality & Purpose | Spiritual path, dharma, inner-shift timing |
DASHA_TRANSIT | Dashas & Transits | Current / next dasha, Sade Sati, eclipses |
Persona rules
- Vedic only. Send ac: "VEDIC" or leave ac out. WESTERN returns 400 for specialist personas.
- Partner chart. pd.partner is used by LOVE and MARRIAGE only.
- One persona per session. Keep the same ap for a sid. Start a new session to switch personas. Off-topic questions get a redirect to the right persona.
- Gender is strongly recommended. Include gender in pd. It changes marriage and matching readings.
Send a specialist question
Send this body to the same Chat API endpoint with the same server-held access token. This example omits ac to use Vedic. Keep birth details inside pd.
{
"q": "Which field suits me best?",
"ap": "CAREER",
"pd": {
"name": "Sita Devi",
"gender": "female",
"language": "en",
"day": 15,
"month": 8,
"year": 1990,
"hour": 10,
"min": 30,
"lat": 28.6139,
"lon": 77.209,
"tzone": 5.5,
"place": "New Delhi"
}
}Reuse the returned session_id as sid and keep ap: CAREER for follow-up questions. Read the answer from response as before.
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
successin 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.