Custom API Integration — Connect Appalix to Any Platform

What you'll need

• An Appalix account on any plan
• A Custom API integration created in your dashboard
• The ability to make HTTP POST requests from your application

Step 1 — Create a Custom API integration

1. Go to Integrations → Add integration and choose Custom API.
2. Name the integration and select a bot. Click Create integration.
3. Open the integration setup page — you'll find your API Key and Endpoint URL there.

The API key is generated automatically when you create the integration. It cannot be recovered after creation, so copy it to a secure location. If you lose it, delete and recreate the integration.

API Reference

POST /chat/custom/:integrationId

Send a message and receive the AI reply synchronously.

Request headers

Content-Type: application/json
x-api-key: sk-YourApiKeyHere

Request body

{
  "message": "What are your pricing plans?",   // required
  "user_id": "user_abc123",                    // optional — identifies the user
  "conversation_id": "conv_xyz789"             // optional — resumes an existing conversation
}

Response body

{
  "reply": "We offer four plans: Starter, Core, Pro, and Scale...",
  "conversation_id": "conv_xyz789"
}

Pass the returned conversation_id back in subsequent requests to maintain conversation history and memory.

Code examples

cURL

curl -X POST 'https://api.appalix.ai/chat/custom/your-integration-id' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-YourApiKey' \
  -d '{"message":"Hello!","user_id":"user_123"}'

JavaScript / TypeScript

const ENDPOINT = 'https://api.appalix.ai/chat/custom/your-integration-id'
const API_KEY  = 'sk-YourApiKey'

async function chat(message: string, conversationId?: string) {
  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({ message, conversation_id: conversationId }),
  })
  if (!res.ok) throw new Error(`Appalix error: ${res.status}`)
  return res.json() as Promise<{ reply: string; conversation_id: string }>
}

// Usage
const { reply, conversation_id } = await chat('What can you help with?')
console.log(reply)
// Continue the conversation
const next = await chat('Tell me more', conversation_id)

Python

import requests

ENDPOINT = 'https://api.appalix.ai/chat/custom/your-integration-id'
API_KEY  = 'sk-YourApiKey'

def chat(message, conversation_id=None):
    res = requests.post(
        ENDPOINT,
        headers={'Content-Type': 'application/json', 'x-api-key': API_KEY},
        json={'message': message, 'conversation_id': conversation_id},
        timeout=30,
    )
    res.raise_for_status()
    return res.json()

data = chat('What services do you offer?')
print(data['reply'])
followup = chat('How much does it cost?', data['conversation_id'])

Error codes

Tips & best practices

• Always pass conversation_id — store it client-side after the first message and include it in every subsequent request to enable memory and context.
• Keep the API key server-side — never expose it in browser JavaScript or mobile app bundles. Route all API calls through your backend.
• Set a timeout — AI responses typically arrive within 3–8 seconds, but set a 30-second timeout to handle rare slow responses gracefully.
• Handle 429 gracefully — on rate limit errors, surface a friendly "I'm busy right now, try again in a moment" message and retry after 5 seconds.
• Allowed IPs — in the integration edit page you can restrict API calls to specific IP addresses (e.g. your server IPs) for an extra layer of security.