botserver/docs/reference/basic-language.md

BASIC Language Reference

Complete reference for General Bots BASIC dialog scripting language.

Overview

General Bots BASIC is a domain-specific language for creating conversational AI dialogs. It provides keywords for:

• User interaction (TALK, HEAR)
• Knowledge base management (USE KB, CLEAR KB)
• Tool registration (USE TOOL, CLEAR TOOLS)
• Data operations (SAVE, GET, POST)
• File handling (SEND FILE, DOWNLOAD)
• Flow control (IF/THEN/ELSE, FOR/NEXT)

Conversation Keywords

TALK

Send a message to the user.

TALK "Hello, how can I help you?"
TALK "Your order number is: " + ordernumber

Multi-line Messages

BEGIN TALK
    **Welcome!**
    
    I can help you with:
    • Orders
    • Shipping
    • Returns
END TALK

HEAR

Wait for and capture user input.

answer = HEAR
name = HEAR AS NAME
email = HEAR AS EMAIL
choice = HEAR AS "Option A", "Option B", "Option C"
confirmed = HEAR AS BOOLEAN

Input Types

Type	Description	Example
STRING	Free text	answer = HEAR
NAME	Person name	name = HEAR AS NAME
EMAIL	Email address	email = HEAR AS EMAIL
PHONE	Phone number	phone = HEAR AS PHONE
INTEGER	Whole number	count = HEAR AS INTEGER
NUMBER	Decimal number	amount = HEAR AS NUMBER
BOOLEAN	Yes/No	confirm = HEAR AS BOOLEAN
DATE	Date value	date = HEAR AS DATE
Options	Multiple choice	choice = HEAR AS "A", "B", "C"

WAIT

Pause execution for specified seconds.

WAIT 5
TALK "Processing..."
WAIT 2
TALK "Done!"

Knowledge Base Keywords

USE KB

Load a knowledge base into the current session.

USE KB "company-docs"
USE KB "product-catalog.gbkb"

CLEAR KB

Remove knowledge base from session.

CLEAR KB "company-docs"
CLEAR KB  ' Clear all KBs

Tool Keywords

USE TOOL

Register a tool for the AI to call.

USE TOOL "create-ticket"
USE TOOL "send-email"
USE TOOL "search-orders"

CLEAR TOOLS

Remove all registered tools.

CLEAR TOOLS

Context Keywords

SET CONTEXT

Define AI behavior context.

SET CONTEXT "assistant" AS "You are a helpful customer service agent for Acme Corp."

System Prompt

Define detailed AI instructions.

BEGIN SYSTEM PROMPT
    You are a professional assistant.
    Always be polite and helpful.
    If you don't know something, say so.
    Never make up information.
END SYSTEM PROMPT

Suggestion Keywords

ADD SUGGESTION

Add a quick-reply button for users.

ADD SUGGESTION "help" AS "Show help"
ADD SUGGESTION "order" AS "Track my order"
ADD SUGGESTION "contact" AS "Contact support"

CLEAR SUGGESTIONS

Remove all suggestions.

CLEAR SUGGESTIONS

Data Keywords

SAVE

Save data to storage.

SAVE "contacts.csv", name, email, phone
SAVE "orders.csv", orderid, product, quantity, total

GET

HTTP GET request.

data = GET "https://api.example.com/users"
weather = GET "https://api.weather.com/current?city=" + city

POST

HTTP POST request.

result = POST "https://api.example.com/orders", orderdata

PUT

HTTP PUT request.

result = PUT "https://api.example.com/users/" + userid, userdata

DELETE HTTP

HTTP DELETE request.

result = DELETE HTTP "https://api.example.com/users/" + userid

SET HEADER

Set HTTP header for requests.

SET HEADER "Authorization" = "Bearer " + token
SET HEADER "Content-Type" = "application/json"
data = GET "https://api.example.com/protected"

CLEAR HEADERS

Remove all custom headers.

CLEAR HEADERS

File Keywords

SEND FILE

Send a file to the user.

SEND FILE "report.pdf"
SEND FILE filepath

DOWNLOAD

Download a file from URL.

file = DOWNLOAD "https://example.com/document.pdf"
SEND FILE file

DELETE FILE

Delete a file from storage.

DELETE FILE "old-report.pdf"

Email Keywords

SEND MAIL

Send an email.

SEND MAIL "recipient@example.com", "Subject Line", "Email body text"
SEND MAIL email, subject, body

Memory Keywords

SET BOT MEMORY

Store a value in bot memory (persists across sessions).

SET BOT MEMORY "last_order", orderid
SET BOT MEMORY "user_preference", preference

GET BOT MEMORY

Retrieve a value from bot memory.

lastorder = GET BOT MEMORY("last_order")
pref = GET BOT MEMORY("user_preference")

Schedule Keywords

SET SCHEDULE

Define when a job should run (cron format).

SET SCHEDULE "0 9 * * *"     ' Daily at 9 AM
SET SCHEDULE "0 0 * * 1"     ' Weekly on Monday
SET SCHEDULE "0 8 1 * *"     ' Monthly on the 1st at 8 AM

Cron Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Flow Control

IF/THEN/ELSE

Conditional execution.

IF status = "active" THEN
    TALK "Your account is active."
ELSE IF status = "pending" THEN
    TALK "Your account is pending approval."
ELSE
    TALK "Your account is inactive."
END IF

FOR/NEXT

Loop through a range.

FOR i = 1 TO 10
    TALK "Item " + i
NEXT

FOR EACH

Loop through a collection.

FOR EACH item IN items
    TALK item.name + ": $" + item.price
END FOR

Variables

Declaration

let name = "John"
let count = 42
let price = 19.99
let active = TRUE

String Operations

let greeting = "Hello, " + name + "!"
let upper = UCASE(text)
let lower = LCASE(text)
let length = LEN(text)
let part = MID(text, 1, 5)

Array Operations

let items = SPLIT(text, ",")
let first = items[0]
let count = LEN(items)

Tool Definition

Tools are BASIC files that the AI can call.

Structure

' tool-name.bas

PARAM parametername AS TYPE LIKE "example" DESCRIPTION "What this parameter is"
PARAM optionalparam AS STRING DESCRIPTION "Optional parameter"

DESCRIPTION "What this tool does. Called when user wants to [action]."

' Implementation
IF parametername = "" THEN
    TALK "Please provide the parameter."
    parametername = HEAR
END IF

let result = "processed: " + parametername

SAVE "records.csv", parametername, result

TALK "✅ Done: " + result

RETURN result

Parameter Types

Type	Description
STRING	Text value
INTEGER	Whole number
NUMBER	Decimal number
BOOLEAN	True/False
DATE	Date value
EMAIL	Email address
PHONE	Phone number

Comments

' This is a single-line comment

REM This is also a comment

' Multi-line comments use multiple single-line comments
' Line 1
' Line 2

Built-in Functions

String Functions

Function	Description	Example
LEN(s)	String length	LEN("hello") → 5
UCASE(s)	Uppercase	UCASE("hello") → "HELLO"
LCASE(s)	Lowercase	LCASE("HELLO") → "hello"
TRIM(s)	Remove whitespace	TRIM(" hi ") → "hi"
MID(s,start,len)	Substring	MID("hello",2,3) → "ell"
LEFT(s,n)	Left characters	LEFT("hello",2) → "he"
RIGHT(s,n)	Right characters	RIGHT("hello",2) → "lo"
SPLIT(s,delim)	Split to array	SPLIT("a,b,c",",") → ["a","b","c"]
REPLACE(s,old,new)	Replace text	REPLACE("hello","l","x") → "hexxo"

Date Functions

Function	Description	Example
NOW()	Current datetime	NOW()
TODAY()	Current date	TODAY()
YEAR(d)	Extract year	YEAR(date) → 2024
MONTH(d)	Extract month	MONTH(date) → 12
DAY(d)	Extract day	DAY(date) → 15
DATEADD(d,n,unit)	Add to date	DATEADD(date,7,"days")
DATEDIFF(d1,d2,unit)	Date difference	DATEDIFF(date1,date2,"days")

Math Functions

Function	Description	Example
ABS(n)	Absolute value	ABS(-5) → 5
ROUND(n,d)	Round number	ROUND(3.456,2) → 3.46
FLOOR(n)	Round down	FLOOR(3.7) → 3
CEILING(n)	Round up	CEILING(3.2) → 4
MIN(a,b)	Minimum	MIN(5,3) → 3
MAX(a,b)	Maximum	MAX(5,3) → 5
SUM(arr)	Sum of array	SUM(numbers)
AVG(arr)	Average	AVG(numbers)

Conversion Functions

Function	Description	Example
STR(n)	Number to string	STR(42) → "42"
VAL(s)	String to number	VAL("42") → 42
INT(n)	To integer	INT(3.7) → 3

Complete Example

' customer-support.bas - Main support dialog

' Setup
USE KB "support-docs"
USE TOOL "create-ticket"
USE TOOL "check-order"
USE TOOL "request-refund"

SET CONTEXT "support" AS "You are a helpful customer support agent for Acme Store."

' Welcome
BEGIN TALK
    **Welcome to Acme Support!**
    
    I can help you with:
    • Order tracking
    • Returns and refunds
    • Product questions
END TALK

' Quick actions
CLEAR SUGGESTIONS
ADD SUGGESTION "order" AS "Track my order"
ADD SUGGESTION "return" AS "Request a return"
ADD SUGGESTION "help" AS "Other questions"

BEGIN SYSTEM PROMPT
    Be friendly and professional.
    Always verify order numbers before making changes.
    For refunds over $100, escalate to human support.
    If asked about competitors, politely redirect to our products.
END SYSTEM PROMPT

Keyword Quick Reference

Category	Keywords
Conversation	TALK, HEAR, WAIT
Knowledge	USE KB, CLEAR KB
Tools	USE TOOL, CLEAR TOOLS
Context	SET CONTEXT, SYSTEM PROMPT
Suggestions	ADD SUGGESTION, CLEAR SUGGESTIONS
Data	SAVE, GET, POST, PUT, DELETE HTTP
HTTP	SET HEADER, CLEAR HEADERS
Files	SEND FILE, DOWNLOAD, DELETE FILE
Email	SEND MAIL
Memory	SET BOT MEMORY, GET BOT MEMORY
Schedule	SET SCHEDULE
Flow	IF/THEN/ELSE/END IF, FOR/NEXT, FOR EACH
Tools	PARAM, DESCRIPTION, RETURN