Ban API - Control User Access to Your Chatbot

The Ban API allows you to temporarily restrict a user's ability to interact with your chatbot. This is useful for implementing:

Credit-based usage systems
Free trial limitations
Usage quotas
Account restrictions

When a user is banned, they can still access the chatbot interface, but instead of getting normal responses, they'll receive your custom message explaining why their access is limited.

API Endpoint

POST https://www.askyourdatabase.com/api/chatbot/v2/ban

Authentication

Authentication requires your API key in the Authorization header:

Authorization: Bearer ${API_KEY}

To get an API key, create one in the API Key page.

Request Parameters

Parameter	Type	Required	Description
chatbotid	string	Yes	The ID of your chatbot
email	string	Yes	The email of the user to ban/unban
action	string	Yes	Either "ban" or "unban"
prompt	string	No	Custom message to show the banned user (only for "ban" action)

Example: Banning a User

curl --location 'https://www.askyourdatabase.com/api/chatbot/v2/ban' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${API_KEY}' \
--data-raw '{
    "chatbotid": "${botid}",
    "email": "user@example.com",
    "action": "ban",
    "prompt": "You have used up all your free credits. Please upgrade your account to continue."
}'

Example: Unbanning a User

curl --location 'https://www.askyourdatabase.com/api/chatbot/v2/ban' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${API_KEY}' \
--data-raw '{
    "chatbotid": "${botid}",
    "email": "user@example.com",
    "action": "unban"
}'

Response Format

A successful ban operation returns:

{
    "success": true,
    "message": "Customer banned successfully",
    "customerId": 3211,
    "config": {
        "AYD_BANNED": true,
        "AYD_BAN_PROMPT": "You have used up all free credits",
        "AYD_BAN_TIMESTAMP": "2025-04-25T17:45:47.890Z"
    }
}

A successful unban operation returns:

{
    "success": true,
    "message": "Customer unbanned successfully",
    "customerId": 3211,
    "config": {}
}

Implementation Example

Here's how you might implement usage limits with this API:

async function checkAndEnforceUsageLimits(userEmail, chatbotId) {
  // Get user's current usage count
  const usage = await getUserUsage(userEmail);
  
  // If usage exceeds limit, ban the user
  if (usage >= USER_CREDIT_LIMIT) {
    const response = await fetch("https://www.askyourdatabase.com/api/chatbot/v2/ban", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.AYD_API_KEY}`,
      },
      body: JSON.stringify({
        chatbotid: chatbotId,
        email: userEmail,
        action: "ban",
        prompt: "You have used all your available credits. Please upgrade your plan to continue."
      }),
    });
    
    return response.json();
  }
  
  return { success: true, message: "User has available credits" };
}

Common Use Cases

Freemium Models: Limit free users to a certain number of questions
Credit Systems: Ban users who have depleted their credits until they purchase more
Trial Periods: Automatically restrict access after trial expiration
Payment Enforcement: Temporarily ban users with failed payments

Notes

Banned users will still be able to access the chatbot interface
When banned, users will see your custom message instead of normal chatbot responses
Ban status persists until you explicitly unban the user through the API
The ban status is stored with the customer profile in your chatbot configuration

Embed Chatbot Getting Started