AI Chatbot - API Documentation
Full reference for all commands, modes, and background jobs.
In all URLs below, replace XXX with your AI Apps Account ID, found in your account settings.
How Endpoints Work
Two ways to call each endpoint - read this first
App Command (API Call)
POST your request to
Mode / Webhook (Direct URL)
POST directly to the endpoint URL shown in each section. The fields go in the POST body as standard form fields (the same fields you would include in an HTML form POST). Use this method for provider webhooks, website forms, or any third-party system that sends form data. No API key is required - the account ID is part of the URL.
POST your request to
https://api.aiappsapi.com with your API key and account ID in the POST body. The fields described in each section below go inside the jsonData POST field as a JSON-encoded string. Use this method when your server is making the call and you have your API credentials available.Mode / Webhook (Direct URL)
POST directly to the endpoint URL shown in each section. The fields go in the POST body as standard form fields (the same fields you would include in an HTML form POST). Use this method for provider webhooks, website forms, or any third-party system that sends form data. No API key is required - the account ID is part of the URL.
Chatbot types: Each chatbot is configured with a type in the admin area. Available types are
support (customer support), sales (sales assistant), storyteller (interactive fiction), gamehost (multiplayer game host), and offerpath (lead generation). The type determines how the chatbot behaves and what built-in features are active.
Send Message
command: chatbotmessage
Send a message to one of your chatbots and receive an AI-generated response. The chatbot will search your knowledge base for relevant information, maintain conversation history, and follow any custom rules you have configured. Supports both text and voice input. Returns the chatbot's response along with a conversation ID for continuing the conversation.
POST App Command URL
https://api.aiappsapi.com app: chatbot command: chatbotmessage
This command is only available as an App Command. Use the Webhook endpoint below for direct URL access without an API key.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Message | prompt | The user's message to the chatbot. Required unless sending a voice message with audioPrompt. |
| Chatbot ID | chatbotID | The ID of the chatbot to send the message to. This is the index number of the chatbot in your chatbots list (starting from 0). |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Conversation ID | convoID | Continue an existing conversation. If omitted, a new conversation is created. The response includes the conversation ID for future messages. |
| Voice Message | audioPrompt | Base64-encoded audio data. When provided, the audio is transcribed and used as the message instead of prompt. |
| Additional Rules | passedRules | Extra instructions to add to the chatbot's system prompt for this message only. |
| Moderation Actions | actionsList | JSON object defining automatic actions the chatbot can take. Supported actions: cleanup (filter profanity), escalate (flag for human review), angry (handle frustrated users). |
| AI Options | options | JSON object to override default AI settings. Keys: maxTokens (default 2000), temperature (default 0.5), numKnowledgeBlocks (knowledge results to include), numOldMessages (conversation history messages to include). |
| User Knowledge Tag | userKnowledgeBase | Tag name for per-user memory. When set, the chatbot also searches the user's personal knowledge base for relevant context. |
| User Info | userInfo | JSON object with information about the user (name, email, etc.) to include in the chatbot's context. |
| Game Rules | gameRules | Custom game rules for gamehost type chatbots. Defines the game scenario and mechanics. |
| Player Name | player | Current player's name for gamehost type chatbots. |
| Player Data | playerData | JSON object with current player stats and inventory for gamehost type chatbots. |
| Start Data | startData | Initial game state data for gamehost type chatbots when starting a new game. |
| Number of Players | numPlayers | Number of players for multiplayer gamehost type chatbots. Range: 1-10. |
Webhook
mode: webhook
Send messages to your chatbot from any external system using a direct URL. This works the same as the Send Message command but does not require an API key. The chatbot must have webhooks enabled in the admin area.
POST Mode URL (no API key needed)
https://api.aiappsapi.com/XXX/chatbot/webhook
The chatbot must have the Allow Webhook setting enabled in the admin area. All fields from the Send Message command above are accepted.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Chatbot ID | chatbotID | The ID of the chatbot. Must have webhooks enabled. |
| Message | prompt | The message to send to the chatbot. |
Embeddable Chat Widget
mode: loadchatbot
Load a full chat interface as an HTML page. Embed this URL in an iframe on your website or link to it directly to give your visitors access to your chatbot. The widget includes a text input, optional voice recording button, animated text display, and automatic conversation history. No API key is needed.
Widget URL
https://api.aiappsapi.com/XXX/chatbot/loadchatbot/{chatbotID}/{convoID}
This is a browser URL, not a POST endpoint. Open it in a browser or embed it in an iframe. The
convoID segment is optional -- omit it to start a new conversation.URL Segments
| Field Name | Segment | Notes |
|---|---|---|
| Chatbot ID | {chatbotID} | The ID of the chatbot to display. This is the index number from your chatbots list. |
| Conversation ID | {convoID} | Optional. Pass an existing conversation ID to reload that conversation's history (if the chatbot has history reload enabled). |
Chat Widget Message Handler
mode: ajaxmessage
Internal endpoint used by the embeddable chat widget to send and receive messages. You can also call this directly from your own JavaScript code to build a custom chat interface without using the built-in widget.
POST Mode URL (no API key needed)
https://api.aiappsapi.com/XXX/chatbot/ajaxmessage
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Message | prompt | The user's message text. Required unless sending voice with audioPrompt. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Conversation ID | convoID | Continue an existing conversation. The response includes the conversation ID. |
| Chatbot ID | chatbotID | Which chatbot to message. Defaults to 0 (your first chatbot). |
| Voice Message | audioPrompt | Base64-encoded audio recording. Used instead of text prompt when provided. |
Search Knowledge Base
command: knowledgebasesearch
Search your knowledge base directly without sending a chatbot message. Returns the most relevant knowledge base entries that match your search text. Useful for building custom search interfaces or checking what information your chatbot has access to.
POST App Command URL
https://api.aiappsapi.com app: chatbot command: knowledgebasesearch
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Search Text | prompt | The text to search for in your knowledge base. The system finds the most relevant matches. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Chatbot ID | chatbotID | Use the tag and settings from this chatbot to filter results. Defaults to 0. |
| Tag | tag | Search only knowledge base entries with this tag. Overrides the chatbot's default tag. |
Store Knowledge Data
command: storedata
Add new information to your chatbot's knowledge base. The content is processed and stored so your chatbot can reference it when answering questions. Use tags to organize your knowledge into categories that different chatbots can access.
POST App Command URL
https://api.aiappsapi.com app: chatbot command: storedata
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Content | data | The text content to store in the knowledge base. Plain text, 250-2000 characters recommended per entry. |
| Tag | tag | A category tag for this knowledge entry. Chatbots configured with this tag will be able to reference this information. |
Store User Memory
command: storeusermemory
Store persistent memory for an individual user. Unlike conversation history which expires, user memory is stored permanently in the knowledge base and is available across all future conversations. Use this to remember user preferences, past interactions, or any information that should persist.
POST App Command URL
https://api.aiappsapi.com app: chatbot command: storeusermemory
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Memory Content | data | The information to remember about this user. Plain text, 250-2000 characters recommended. |
| User Tag | tag | A unique identifier for the user (such as their email or user ID). All memories with the same tag are grouped together. |
Crawl Website
job: crawlwebsite
Automatically crawl a website and add all of its content to your chatbot's knowledge base. The crawler follows links on the same domain, extracts the text content from each page, and stores it as searchable knowledge entries. This runs as a background job because it can take time to process many pages.
POST App Command URL (Background Job)
https://api.aiappsapi.com app: chatbot job: crawlwebsite
This runs as a background job. Large websites may take several minutes to process. The crawler only follows links within the same domain.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Website URL | url | The starting URL to crawl. The crawler will follow links from this page to discover other pages on the same domain. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Tag | tag | Category tag for the crawled content. Defaults to the website's domain name (with dots replaced by hyphens). |
| Max Pages | maxPages | Maximum number of pages to crawl. Default: 50, maximum: 200. |
Email Monitoring
Scheduled task - configured in admin
When enabled, the system automatically monitors your configured email accounts for incoming messages. When a new email arrives, it is forwarded to your chatbot for processing. The chatbot generates a response and sends it back to the sender as a reply email. Conversation continuity is maintained through ticket numbers in the email subject line.
This is a scheduled background task with no API endpoint. Configure your email accounts in the admin area under the chatbot settings. Each email account needs a host, username, password, alias (the email address to monitor), and the chatbot ID to handle responses.