Aksita.ai Logo Docs

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

ParameterTypeRequiredDescription
messagestringYesThe text message to send to the agent.
conversation_idstringYesThe unique session ID returned by the Create Session endpoint.
additional_contextstringNoOptional 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"
  },
  "detail": "response generated successfully"
}

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

Session does not exist or invalid ID

404 Not Found
{
  "status": false,
  "reason": "conversation not found"
}

Insufficient credits

402 Payment Required
{
  "status": false,
  "reason": "Insufficient credits"
}