Menggunakan Agent

Integrasi API

Integrasikan agent dengan aplikasi Anda menggunakan REST API

Tentang API Integration

API Integration memungkinkan Anda mengintegrasikan agent dengan aplikasi custom, mobile app, atau platform lain. Dengan API, Anda punya kontrol penuh atas UI/UX dan dapat mengembangkan pengalaman chat yang unik.

Use Cases:

  • Integrasi dengan mobile app (iOS/Android)
  • Custom web application dengan UI sendiri
  • Desktop app atau SaaS platform
  • Integrasi dengan sistem internal
1

Mendapatkan API Key

Untuk menggunakan API, Anda perlu API Key:

  1. 1
    Buka halaman API Keys

    Di dashboard, pilih agent → API Keys

  2. 2
    Buat API Key baru

    Klik "Create API Key" dan beri nama

  3. 3
    Copy & Simpan

    Copy API Key dan simpan di tempat aman

Penting:

API Key hanya ditampilkan sekali saat pembuatan. Jika hilang, Anda harus membuat key baru.

2

Endpoint API Utama

POST /api/session

Buat session (conversation) baru untuk chat

Headers:
  X-API-Key: YOUR_API_KEY

Response:
{
  "conversation_id": "conv-abc-123"
}
POST /api/chat

Kirim pesan ke agent dan dapatkan response

Headers:
  X-API-Key: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "conversation_id": "conv-abc-123",
  "message": "Hello, what can you help me with?"
}

Catatan:

API menggunakan X-API-Key header untuk autentikasi. Dapatkan API Key dari halaman API Keys di dashboard.

3

Contoh Implementasi

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://api.aksita.ai';

// Step 1: Create session
async function createSession() {
  const response = await axios.post(
    `${BASE_URL}/api/session`,
    {},
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data.data.conversation_id;
}

// Step 2: Send message
async function sendMessage(conversationId, message) {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/chat`,
      {
        conversation_id: conversationId,
        message: message
      },
      {
        headers: {
          'X-API-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data.data;
  } catch (error) {
    if (error.response) {
      // API error with response
      console.error('API Error:', error.response.data.reason);
    } else {
      // Network error
      console.error('Network Error:', error.message);
    }
    throw error;
  }
}

// Usage
(async () => {
  const sessionId = await createSession();
  console.log('Session created:', sessionId);
  
  const response = await sendMessage(sessionId, 'Hello!');
  console.log('Agent response:', response.response);
  console.log('Credits used:', response.credits);
  console.log('Remaining credits:', response.remaining_credits);
})();
4

Format Response

API mengembalikan response dalam format JSON dengan wrapper standar:

{
  "status": true,
  "data": {
    "response": [
      "Hello! I'm here to help you...",
      "What can I do for you today?"
    ],
    "credits": 15,
    "remaining_credits": 9985,
    "message_id": "msg-xyz-789",
    "conversation_id": "conv-abc-123"
  },
  "detail": "Response generated successfully"
}
status

Status keberhasilan request (true/false)

response

Array of response text dari agent

credits

Credits yang digunakan untuk request ini

remaining_credits

Sisa credits setelah request ini

message_id

ID message yang tersimpan

conversation_id

ID conversation untuk context tracking

Error Handling

Error dikembalikan dalam format JSON dengan status: false dan field reason:

{
  "status": false,
  "reason": "Descriptive error message"
}
400 Bad Request

Request format salah atau parameter required missing (conversation_id, message).

401 Unauthorized

X-API-Key tidak valid, missing, atau revoked. Periksa kembali API Key Anda.

402 Payment Required

Credits habis atau plan expired. Top up credits atau renew subscription.

403 Forbidden

Agent is disabled, deleted, atau access tidak diizinkan.

404 Not Found

Conversation ID tidak ditemukan atau agent tidak exist.

500 Internal Server Error

Error di server. Retry setelah beberapa saat. Gunakan exponential backoff.

Tip:

Lihat halaman Error Codes di dokumentasi API untuk detail lengkap dan contoh error handling.

Best Practices

Secure API Key

Jangan expose API Key di frontend. Gunakan backend sebagai proxy.

Handle Errors

Implementasi error handling yang proper untuk user experience yang baik.

Reuse Conversations

Gunakan conversation_id yang sama untuk context awareness dalam sesi yang sama.

Monitor Credits

Track credit usage dari response untuk manage costs dan budget.

Dokumentasi Lengkap

Untuk dokumentasi API lengkap dengan semua endpoints, parameters, dan examples:

Buka API Documentation