If you're a developer and want to integrate AllAI functionality into a mobile app, a custom CRM, an internal dashboard, or any other system, our REST API is your tool. This guide covers everything you need: from authentication and main endpoints to webhooks, code examples, and best practices.

REST API Overview

The AllAI API follows standard REST principles:

  • Base URL: https://api.allai.ro/v2/
  • Format: JSON for request and response
  • Versioning: Current version is v2 (v1 remains active for backward compatibility)
  • HTTPS required: All requests must be made over HTTPS
  • Encoding: UTF-8

Full interactive documentation (Swagger/OpenAPI) is available at https://api.allai.ro/docs.

Authentication (API Keys)

All API requests require authentication via API key. Here's how to obtain and use your key:

Obtaining an API Key

  1. Go to AllAI Dashboard > Settings > API
  2. Click on "Generate New API Key"
  3. Name the key (e.g., "Mobile App Production")
  4. Select permissions (read, write, admin)
  5. Copy the generated key — it is displayed only once

Using in Requests

Send the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
⚠️ Security

Never expose the API key in client-side code (JavaScript frontend, decompilable mobile apps). Use it only on the server-side. For frontend integrations, use session tokens (see the Session Tokens section below).

Session Tokens (for Frontend)

For client-side integrations, generate a session token from your backend:

POST /v2/auth/session-token
{
    "chatbot_id": "cb_abc123",
    "visitor_id": "visitor_xyz",
    "expires_in": 3600
}

// Response:
{
    "session_token": "st_live_...",
    "expires_at": "2026-01-19T15:30:00Z"
}

The session token has limited permissions (conversation only) and expires automatically.

Main Endpoints

/conversations — Conversation Management

// List conversations
GET /v2/conversations?status=active&limit=50&offset=0

// Conversation details
GET /v2/conversations/{conversation_id}

// Create new conversation
POST /v2/conversations
{
    "chatbot_id": "cb_abc123",
    "visitor": {
        "name": "Ion Popescu",
        "email": "ion@exemplu.ro"
    },
    "channel": "api",
    "metadata": {
        "source": "mobile_app",
        "page": "/produse/laptop-x"
    }
}

// Close conversation
PATCH /v2/conversations/{conversation_id}
{
    "status": "closed",
    "resolution": "resolved_by_bot"
}

/messages — Sending and Receiving Messages

// Send message in conversation
POST /v2/conversations/{conversation_id}/messages
{
    "content": "Hello, I'd like information about product X",
    "role": "visitor",
    "type": "text"
}

// Response (includes AI response):
{
    "visitor_message": {
        "id": "msg_001",
        "content": "Hello, I'd like information about product X",
        "timestamp": "2026-01-19T10:30:00Z"
    },
    "bot_response": {
        "id": "msg_002",
        "content": "Hello! Product X is available...",
        "confidence": 0.94,
        "sources": ["kb_article_15", "kb_article_23"],
        "timestamp": "2026-01-19T10:30:01Z"
    }
}

// List messages from conversation
GET /v2/conversations/{conversation_id}/messages?limit=100

/contacts — Contact Management

// List contacts
GET /v2/contacts?search=ion@exemplu.ro

// Create contact
POST /v2/contacts
{
    "name": "Ion Popescu",
    "email": "ion@exemplu.ro",
    "phone": "+40722123456",
    "tags": ["lead", "interested-product-x"],
    "custom_fields": {
        "company": "SRL Example",
        "industry": "retail"
    }
}

// Update contact
PUT /v2/contacts/{contact_id}

// Contact conversation history
GET /v2/contacts/{contact_id}/conversations

/analytics — Data and Reports

// General statistics
GET /v2/analytics/overview?period=30d

// Response:
{
    "total_conversations": 1847,
    "resolution_rate": 0.82,
    "avg_response_time_ms": 680,
    "satisfaction_score": 4.3,
    "top_topics": [
        {"topic": "pricing", "count": 312},
        {"topic": "shipping", "count": 287},
        {"topic": "returns", "count": 156}
    ],
    "conversations_by_channel": {
        "website": 1203,
        "whatsapp": 412,
        "messenger": 232
    }
}

// Conversations per day
GET /v2/analytics/conversations?period=30d&granularity=day

// Satisfaction report
GET /v2/analytics/satisfaction?period=30d

Webhooks: Real-Time Notifications

Webhooks send HTTP POST notifications to your URL every time an event occurs. They are essential for reactive integrations.

Webhook Configuration

POST /v2/webhooks
{
    "url": "https://api.your-site.com/allai-webhook",
    "events": [
        "conversation.started",
        "conversation.ended",
        "message.received",
        "lead.created",
        "handoff.requested"
    ],
    "secret": "webhook_secret_for_verification"
}

Available Events

  • conversation.started — A new conversation has started
  • conversation.ended — A conversation has closed
  • message.received — A new message from the visitor
  • message.sent — The chatbot sent a response
  • lead.created — A new lead has been identified
  • lead.qualified — A lead has been automatically qualified
  • handoff.requested — The chatbot requests transfer to a human agent
  • satisfaction.rated — The customer gave a satisfaction rating

Signature Verification

Each webhook includes an X-AllAI-Signature header for verification:

// Verification in Node.js
const crypto = require('crypto');
const signature = req.headers['x-allai-signature'];
const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

if (signature === hash) {
    // Valid webhook, process
} else {
    // Invalid webhook, reject
}
💡 Pro Tip

Configure webhooks to return status 200 quickly (under 5 seconds) and process data asynchronously. If your endpoint doesn't respond within 30 seconds, AllAI will retry 3 times with exponential backoff.

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const allai = axios.create({
    baseURL: 'https://api.allai.ro/v2',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
});

// Send a message and get the AI response
async function sendMessage(conversationId, message) {
    const response = await allai.post(
        `/conversations/${conversationId}/messages`,
        {
            content: message,
            role: 'visitor',
            type: 'text'
        }
    );
    return response.data.bot_response;
}

// Get analytics for the last 30 days
async function getAnalytics() {
    const response = await allai.get('/analytics/overview', {
        params: { period: '30d' }
    });
    return response.data;
}

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.allai.ro/v2'
HEADERS = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Create a new conversation
def create_conversation(chatbot_id, visitor_name, visitor_email):
    response = requests.post(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        json={
            'chatbot_id': chatbot_id,
            'visitor': {
                'name': visitor_name,
                'email': visitor_email
            },
            'channel': 'api'
        }
    )
    return response.json()

# Get all active conversations
def get_active_conversations():
    response = requests.get(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        params={'status': 'active', 'limit': 50}
    )
    return response.json()

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.allai.ro/v2';

// Helper function for API requests
function allaiRequest($method, $endpoint, $data = null) {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// List contacts
$contacts = allaiRequest('GET', '/contacts?limit=100');

// Create lead from form
$newLead = allaiRequest('POST', '/contacts', [
    'name' => 'Maria Popescu',
    'email' => 'maria@exemplu.ro',
    'tags' => ['lead', 'contact-form']
]);
?>

Rate Limits and Best Practices

Request Limits

  • Professional Plan: 1,000 requests/minute
  • Enterprise Plan: 5,000 requests/minute
  • White-Label Plan: 10,000 requests/minute

Responses include headers for monitoring limits:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1706097600

Best Practices

  1. Implement retry with exponential backoff — On 429 (Too Many Requests) or 5xx errors, wait and retry with increasing intervals.
  2. Use pagination — For large listings, use limit and offset instead of requesting all results at once.
  3. Cache static data — Chatbot configuration, integration list, and other data that doesn't change frequently.
  4. Validate webhooks — Always verify the X-AllAI-Signature before processing data.
  5. Handle errors — The API returns standard HTTP codes (400, 401, 403, 404, 429, 500) with descriptive messages.
  6. Use specific fields — The fields parameter allows selecting only the necessary fields, reducing payload size.
⚠️ Important

Don't store API keys in public Git repositories. Use environment variables (.env) or a secrets manager. If an API key is compromised, revoke it immediately from the Dashboard and generate a new one.

Available SDKs

We provide official SDKs to accelerate integration:

  • JavaScript/Node.js — npm install @allai/sdk
  • Python — pip install allai-sdk
  • PHP — composer require allai/sdk

The SDKs include:

  • Wrappers for all API endpoints
  • Automatic rate limit and retry handling
  • TypeScript types for autocompletion
  • Automatic webhook signature verification
  • Built-in logging for debugging

Common Use Cases

Mobile App Integration

Create a native chat experience in your mobile app (iOS/Android). Your backend communicates with the AllAI API, and the frontend displays the conversation in a custom interface.

Custom CRM Integration

Your company has an internally developed CRM. AllAI webhooks send conversation data directly to your CRM, without depending on predefined integrations.

Custom Dashboard

You build an internal dashboard that combines data from AllAI with other sources (sales, marketing, support). The /analytics endpoint provides the necessary data.

Complex Automations

You create complex flows: ERP stock verification, dynamic price calculation, PDF quote generation — all triggered from the chatbot conversation through webhooks.

Testing Sandbox

The sandbox environment allows testing your integration without affecting production data:

  • Sandbox Base URL: https://sandbox.api.allai.ro/v2/
  • Sandbox API Key: Generate separately from Dashboard > Settings > API > Sandbox Tab
  • Test data: Pre-populated fictitious contacts and conversations
  • No charges: Sandbox requests are not counted
  • Reduced rate limit: 100 requests/minute (sufficient for testing)
💡 Pro Tip

Always develop and test in the sandbox before going to production. Use environment variables to easily switch between sandbox.api.allai.ro and api.allai.ro.

Developer Support

If you have questions or encounter issues with the API:

  • Interactive documentation: https://api.allai.ro/docs
  • Status page: https://status.allai.ro for availability monitoring
  • Technical support email: dev@allai.ro
  • Discord community: Join the #developers channel

Ready to integrate AllAI into your project? Generate an API key from the dashboard and start with the sandbox. Or, if you need assistance with your integration architecture, schedule a technical session with our development team.