​
API Reference

AI Chat Assist provides a comprehensive API that allows you to integrate our chatbot functionality into your applications and services.

Authentication

API keys, headers, and base URL details

Chat API

Send messages and fetch chat history

Bot Management

Create, configure, and inspect bots

Lead Management

Create and query leads programmatically

Messaging & Integrations

WhatsApp, webhooks, and external channels

Webhooks & Events

Event payloads, verification, and signatures

​
Authentication

All API requests require authentication using an API key.

curl -X GET "https://api.aichatassist.com/v1/bots" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can obtain your API key from the Settings > API Keys section of your dashboard.

​
Base URL

https://api.aichatassist.com

​
Chat API

​
Send a Message

POST /v1/chat

Send a message to your chatbot and receive a response.

​
Request Body

{
  "bot_id": "bot_123456",
  "message": "What are your business hours?",
  "session_id": "user_session_123",
  "user_info": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

​
Response

{
  "id": "msg_789012",
  "bot_id": "bot_123456",
  "session_id": "user_session_123",
  "message": "Our business hours are Monday to Friday, 9 AM to 5 PM.",
  "created_at": "2025-06-13T06:15:23Z"
}

​
Get Chat History

GET /v1/chat/history/{session_id}

Retrieve the chat history for a specific session.

​
Response

{
  "session_id": "user_session_123",
  "messages": [
    {
      "id": "msg_123456",
      "role": "user",
      "message": "What are your business hours?",
      "created_at": "2025-06-13T06:15:20Z"
    },
    {
      "id": "msg_789012",
      "role": "bot",
      "message": "Our business hours are Monday to Friday, 9 AM to 5 PM.",
      "created_at": "2025-06-13T06:15:23Z"
    }
  ]
}

​
Bot Management API

​
List Bots

GET /v1/bots

Retrieve a list of all your bots.

​
Response

{
  "bots": [
    {
      "id": "bot_123456",
      "name": "Sales Assistant",
      "created_at": "2025-05-01T10:00:00Z",
      "status": "active"
    },
    {
      "id": "bot_789012",
      "name": "Support Bot",
      "created_at": "2025-05-15T14:30:00Z",
      "status": "active"
    }
  ]
}

​
Get Bot Details

GET /v1/bot/{bot_id}

Retrieve details for a specific bot.

​
Response

{
  "id": "bot_123456",
  "name": "Sales Assistant",
  "description": "A bot to assist with sales inquiries",
  "created_at": "2025-05-01T10:00:00Z",
  "updated_at": "2025-06-10T15:45:00Z",
  "status": "active",
  "domains": ["example.com", "shop.example.com"],
  "settings": {
    "welcome_message": "Hello! How can I help you today?",
    "offline_message": "We're currently offline. Please leave a message.",
    "theme": {
      "primary_color": "#A855F7",
      "text_color": "#FFFFFF"
    }
  }
}

​
Lead Management API

​
Create Lead

POST /v1/lead

Create a new lead in the system.

​
Request Body

{
  "bot_id": "bot_123456",
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+1234567890",
  "tags": ["website", "pricing"],
  "custom_fields": {
    "company": "Acme Inc",
    "role": "Marketing Manager"
  }
}

​
Response

{
  "id": "lead_345678",
  "bot_id": "bot_123456",
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+1234567890",
  "tags": ["website", "pricing"],
  "custom_fields": {
    "company": "Acme Inc",
    "role": "Marketing Manager"
  },
  "created_at": "2025-06-13T06:30:00Z"
}

​
List Leads

GET /v1/leads?bot_id={bot_id}

Retrieve a list of leads for a specific bot.

​
Response

{
  "leads": [
    {
      "id": "lead_345678",
      "bot_id": "bot_123456",
      "name": "Jane Smith",
      "email": "[email protected]",
      "created_at": "2025-06-13T06:30:00Z"
    },
    {
      "id": "lead_901234",
      "bot_id": "bot_123456",
      "name": "Bob Johnson",
      "email": "[email protected]",
      "created_at": "2025-06-12T14:15:00Z"
    }
  ]
}

​
Messaging & Integration APIs

This section covers optional integrations that extend chatbots beyond the web widget. The examples use mock data so you can experiment before connecting real accounts.

​
WhatsApp OTP API

Use the OTP API to deliver verification codes to a customer’s WhatsApp inbox. Each OTP is valid for 5 minutes.

​
Send Production OTP

Use this endpoint when invoking the production WhatsApp flow handled by the Access API.

POST https://access.aichatassist.com/api/wp/send-otp
Headers
NameValue
Content-Typeapplication/json
api-keyYour provisioned API key
Body Parameters
NameTypeDescription
recipient_phone_numberstringWhatsApp number (E.164).
otp_codestringOTP to send (generated on your side).
template_namestringApproved template to deliver the OTP message.
sender_phone_numberstringRegistered WhatsApp sender ID.
curl --location 'https://access.aichatassist.com/api/wp/send-otp' \
  --header 'Content-Type: application/json' \
  --header 'api-key: <API_KEY>' \
  --data '{
    "recipient_phone_number": "+918888398350",
    "otp_code": "989809",
    "template_name": "otp_verification",
    "sender_phone_number": "918237911307"
  }'

​
Send OTP

POST /v1/whatsapp/otp/send
Body Parameters
NameTypeDescription
phonestringWhatsApp number in E.164 format.
otp_lengthinteger(Optional) Number of digits to generate. Default: 6.
{
  "phone": "+1234567890",
  "otp_length": 6
}

​
Sample Response

{
  "message_id": "msg_otp_789",
  "status": "sent",
  "expires_in": 300
}

​
Verify OTP

POST /v1/whatsapp/otp/verify

{
  "message_id": "msg_otp_789",
  "otp": "123456"
}

{
  "verified": true
}
Error Response
{
  "error": {
    "code": "otp_invalid",
    "message": "The OTP code is incorrect or expired"
  }
}

​
WhatsApp Broadcasting API

Send templated messages to multiple recipients at once or schedule them for later delivery.

​
Create Broadcast

POST /v1/whatsapp/broadcast

{
  "template": "promo_update",
  "contacts": ["+1987654321", "+1234567890"],
  "parameters": {
    "name": "John"
  }
}

{
  "broadcast_id": "broadcast_456",
  "status": "queued"
}

​
Check Broadcast Status

GET /v1/whatsapp/broadcast/{broadcast_id}

{
  "broadcast_id": "broadcast_456",
  "status": "delivered",
  "sent_count": 2
}

​
Instagram Callbacks

Register a webhook URL to receive events like direct messages or story mentions from your connected Instagram account.

POST /v1/instagram/webhook/subscribe

Instagram will send a GET request to your callback URL containing hub.challenge during verification. Respond with the same value.

​
Sample Event Payload

{
  "object": "instagram",
  "entry": [
    {
      "id": "insta_page_1",
      "changes": [
        {
          "field": "messages",
          "value": {
            "sender": "user_123",
            "message": "Hello from Instagram!"
          }
        }
      ]
    }
  ]
}

​
App Webhook Integration

Create webhooks to notify your application when important events occur within AI Chat Assist.

POST /v1/webhooks

{
  "url": "https://example.com/webhook-endpoint",
  "events": ["lead.qualified", "chat.message.created"],
  "secret": "whsec_test_123"
}

{
  "webhook_id": "wh_001",
  "status": "active"
}

Webhook requests include an X-Signature header containing a HMAC SHA256 signature of the payload. Use the secret value you provided to verify the request.

​
Example Verification Snippet (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
}

​
Marketing Automation API

Notify your CRM or marketing platform when a lead progresses through your funnel.

POST /v1/marketing/lead/notify

{
  "lead_id": "lead_345678",
  "status": "qualified",
  "score": 87,
  "callback_url": "https://example.com/lead-events"
}

{
  "notification_id": "notif_123",
  "delivered": true
}

​
Webhook Events

You can configure webhooks to receive real-time notifications about events in your AI Chat Assist account.

​
Available Events

  • chat.message.created: Triggered when a new message is sent or received
  • lead.created: Triggered when a new lead is created
  • bot.status.changed: Triggered when a bot’s status changes

​
Webhook Payload Example

{
  "event": "lead.created",
  "created_at": "2025-06-13T06:30:00Z",
  "data": {
    "id": "lead_345678",
    "bot_id": "bot_123456",
    "name": "Jane Smith",
    "email": "[email protected]"
  }
}

​
Rate Limits

  • Free plan: 100 requests per minute
  • Pro plan: 500 requests per minute
  • Enterprise plan: Custom limits

If you exceed these limits, you’ll receive a 429 Too Many Requests response.

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request.

  • 200 OK: The request was successful
  • 400 Bad Request: The request was invalid
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: You don’t have permission to access the resource
  • 404 Not Found: The requested resource was not found
  • 429 Too Many Requests: You’ve exceeded the rate limit
  • 500 Internal Server Error: Something went wrong on our end

Error responses include a JSON body with more details:

{
  "error": {
    "code": "invalid_request",
    "message": "The bot_id parameter is required",
    "status": 400
  }
}

​
SDK Libraries

We provide official SDK libraries for popular programming languages:

​
Need Help?

If you have any questions or need assistance with the API, please contact our support team.

AuthenticationWebhooks