Send Message

Sends a user message to the agent within a specific session. The agent will process the message, retrieve relevant context from your knowledge base, and generate a response.

HTTP Request

POST /api/chat

Request Parameters

Parameter	Type	Required	Description
message	string	Yes	The text message to send to the agent.
conversation_id	string	Yes	Session ID from Create Session. If the ID is unknown or deleted, Aksita creates a new conversation and returns it with isfresh=true. Always persist the conversation_id from the response.
additional_context	string	No	Optional context about the user, account, or situation (e.g., user metadata, plan info, account status). This helps the agent provide more personalized responses.

Additional Context (Optional)

The additional_context parameter allows you to inject user-specific information (metadata, account status, plan details, etc.) that the agent can use to provide more personalized and relevant responses.

Use Cases:

User account metadata (name, email, ID, plan type)
Current subscription status and credits
Order/transaction information
Technical context (device, integration status, error logs)

Example with Context

{
  "conversation_id": "conv-abc-123",
  "message": "What is my current plan?",
  "additional_context": "User: John Doe\\nEmail: john@example.com\\nPlan: Premium\\nCredits: 500\\nStatus: Active"
}

Security Note:

Do not include sensitive information like passwords, API keys, or credit card numbers in additional_context. Only include metadata that is safe to expose to the AI.

Request Example

curl -X POST https://api.aksita.ai/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "message": "Hello!",
    "conversation_id": "your-session-id",
    "additional_context": "User: John Doe, Plan: Premium, Credits: 500"
  }'

Success Response

200 OK

{
  "status": true,
  "data": {
    "response": ["I can certainly help with that. Based on our policies..."],
    "credits": 2,
    "remaining_credits": 1234,
    "message_id": "12345",
    "conversation_id": "abc-123-def-456",
    "isfresh": false,
    "additional_context": ""
  },
  "detail": "response generated successfully"
}

isfresh — false when the given conversation_id was valid. true when it was unknown/deleted and Aksita created a new UUID v7 session for this request. Persist the returned conversation_id whenever isfresh is true.

Error Responses

Message is empty or missing

400 Bad Request

{
  "status": false,
  "reason": "message is required"
}

Conversation ID is missing

400 Bad Request

{
  "status": false,
  "reason": "conversation_id is required"
}

Invalid or deleted conversation_id

No longer returns 404. Aksita creates a new session, continues the chat, and responds with 200 and isfresh=true plus the new conversation_id.

Conversation belongs to another agent

403 Forbidden

{
  "status": false,
  "reason": "conversation does not belong to this agent"
}

Insufficient credits

402 Payment Required

{
  "status": false,
  "reason": "Insufficient credits"
}