botserver/docs/NEW_KEYWORDS_REFERENCE.md

General Bots - New Keywords Reference

Complete reference for all new BASIC keywords implemented for General Bots Office Suite

Table of Contents

1. Social Media Keywords
2. Form Handling & Webhooks
3. Template Messaging
4. Lead Scoring & CRM
5. Math Functions
6. Date/Time Functions
7. String Functions
8. Validation Functions
9. Array Functions
10. Error Handling

---

Social Media Keywords

POST TO

Post content to social media platforms.

' Post to single platform
POST TO INSTAGRAM image, "Check out our new feature! #AI #Automation"

' Post to specific platforms
POST TO FACEBOOK image, caption
POST TO LINKEDIN image, caption  
POST TO TWITTER image, caption

' Post to multiple platforms at once
POST TO "instagram,facebook,linkedin" image, caption

POST TO ... AT (Scheduled Posting)

Schedule posts for future publishing.

' Schedule a post
POST TO INSTAGRAM AT "2025-02-01 10:00" image, caption
POST TO FACEBOOK AT "2025-02-15 09:00" image, "Coming soon!"

GET METRICS

Retrieve engagement metrics for posts.

' Get Instagram metrics
metrics = GET INSTAGRAM METRICS "post-id"
TALK "Likes: " + metrics.likes + ", Comments: " + metrics.comments

' Get Facebook metrics
fb_metrics = GET FACEBOOK METRICS "post-id"
TALK "Shares: " + fb_metrics.shares

' Get LinkedIn metrics
li_metrics = GET LINKEDIN METRICS "post-id"

' Get Twitter metrics
tw_metrics = GET TWITTER METRICS "post-id"

GET POSTS

List posts from a platform.

' Get all Instagram posts
posts = GET INSTAGRAM POSTS

' Get Facebook posts
fb_posts = GET FACEBOOK POSTS

DELETE POST

Remove a scheduled or published post.

DELETE POST "post-id"

---

Form Handling & Webhooks

ON FORM SUBMIT

Register webhook handlers for form submissions from landing pages.

' Basic form handler
ON FORM SUBMIT "landing-page-form"
    ' Access form fields
    name = fields.name
    email = fields.email
    phone = fields.phone
    
    ' Access metadata
    source = metadata.utm_source
    referrer = metadata.referrer
    
    ' Process the submission
    SAVE "leads.csv", name, email, phone, source
    SEND MAIL email, "Welcome!", "Thank you for your interest..."
END ON

' Form handler with validation
ON FORM SUBMIT "contact-form" WITH VALIDATION
    ' Validation is automatically applied
    ' Required fields, email format, phone format checked
END ON

WEBHOOK

Create custom webhook endpoints.

' Register a webhook endpoint
WEBHOOK "order-received"

' The webhook will be available at:
' https://your-server/bot-name/webhook/order-received

SET SCHEDULE

Schedule scripts to run at specific times.

' Run daily at 9 AM
SET SCHEDULE "0 9 * * *", "daily-report.bas"

' Run every Monday at 10 AM
SET SCHEDULE "0 10 * * 1", "weekly-summary.bas"

' Run on specific date
SET SCHEDULE DATEADD(TODAY(), 3, "day"), "followup.bas"

---

Template Messaging

SEND TEMPLATE

Send templated messages across multiple channels.

' Send email template
SEND TEMPLATE "welcome", "email", "user@example.com", #{name: "John", product: "Pro Plan"}

' Send WhatsApp template
SEND TEMPLATE "order-confirmation", "whatsapp", "+1234567890", #{order_id: "12345"}

' Send SMS template
SEND TEMPLATE "verification", "sms", "+1234567890", #{code: "123456"}

' Send to multiple channels at once
SEND TEMPLATE "announcement", "email,whatsapp", recipient, variables

' Simplified syntax without variables
SEND TEMPLATE "reminder", "email", "user@example.com"

SEND TEMPLATE TO (Bulk)

Send templates to multiple recipients.

' Bulk email send
recipients = ["a@example.com", "b@example.com", "c@example.com"]
count = SEND TEMPLATE "newsletter" TO "email" recipients, #{month: "January"}
TALK "Sent to " + count + " recipients"

CREATE TEMPLATE

Create new message templates.

' Create email template
CREATE TEMPLATE "welcome", "email", "Welcome to {{company}}!", "Hello {{name}}, thank you for joining us!"

' Create WhatsApp template
CREATE TEMPLATE "order-update", "whatsapp", "", "Your order {{order_id}} is {{status}}."

GET TEMPLATE

Retrieve a template.

template = GET TEMPLATE "welcome"
TALK "Template body: " + template.body

---

Lead Scoring & CRM

SCORE LEAD

Calculate lead score based on profile and behavior data.

' Score a lead
lead_data = NEW OBJECT
lead_data.email = "john@company.com"
lead_data.name = "John Smith"
lead_data.company = "Acme Corp"
lead_data.job_title = "VP of Engineering"
lead_data.industry = "Technology"
lead_data.company_size = "Enterprise"

score = SCORE LEAD lead_data

TALK "Score: " + score.score
TALK "Grade: " + score.grade
TALK "Status: " + score.status
TALK "Recommendations: " + score.recommendations[0]

AI SCORE LEAD

Use AI/LLM-enhanced scoring for better accuracy.

' AI-enhanced scoring
score = AI SCORE LEAD lead_data

TALK "AI Score: " + score.score
TALK "AI Confidence: " + score.breakdown.ai_confidence

GET LEAD SCORE

Retrieve existing lead score.

' Get stored score
score = GET LEAD SCORE "lead-id"
TALK "Current score: " + score.score

QUALIFY LEAD

Check if lead meets qualification threshold.

' Default threshold (70)
result = QUALIFY LEAD "lead-id"
IF result.qualified THEN
    TALK "Lead is qualified: " + result.status
END IF

' Custom threshold
result = QUALIFY LEAD "lead-id", 80
IF result.qualified THEN
    TALK "Lead meets 80+ threshold"
END IF

UPDATE LEAD SCORE

Manually adjust a lead's score.

' Add points for engagement
new_score = UPDATE LEAD SCORE "lead-id", 10, "Attended webinar"

' Deduct points for inactivity
new_score = UPDATE LEAD SCORE "lead-id", -5, "No response to email"

---

Math Functions

Basic Math

' Absolute value
result = ABS(-42)         ' Returns 42

' Rounding
result = ROUND(3.7)       ' Returns 4
result = ROUND(3.14159, 2) ' Returns 3.14

' Integer conversion
result = INT(3.9)         ' Returns 3
result = FIX(-3.9)        ' Returns -3
result = FLOOR(3.7)       ' Returns 3
result = CEIL(3.2)        ' Returns 4

Min/Max

' Two values
result = MAX(10, 20)      ' Returns 20
result = MIN(10, 20)      ' Returns 10

' Array values
arr = [5, 2, 8, 1, 9]
result = MAX(arr)         ' Returns 9
result = MIN(arr)         ' Returns 1

Other Math Functions

' Modulo
result = MOD(17, 5)       ' Returns 2

' Random numbers
result = RANDOM()         ' Random 0-1
result = RANDOM(100)      ' Random 0-99
result = RANDOM(1, 10)    ' Random 1-10

' Sign
result = SGN(-5)          ' Returns -1
result = SGN(5)           ' Returns 1
result = SGN(0)           ' Returns 0

' Square root
result = SQR(16)          ' Returns 4
result = SQRT(25)         ' Returns 5

' Logarithms
result = LOG(10)          ' Natural log
result = LOG10(100)       ' Base 10 log

' Exponential
result = EXP(2)           ' e^2

' Power
result = POW(2, 8)        ' Returns 256
result = POWER(3, 4)      ' Returns 81

' Trigonometry
result = SIN(0)           ' Returns 0
result = COS(0)           ' Returns 1
result = TAN(0)           ' Returns 0
pi = PI()                 ' Returns 3.14159...

' Aggregation
arr = [10, 20, 30, 40, 50]
result = SUM(arr)         ' Returns 150
result = AVG(arr)         ' Returns 30
result = AVERAGE(arr)     ' Returns 30

---

Date/Time Functions

Current Date/Time

' Current date and time
now = NOW()               ' "2025-01-22 14:30:45"
now_utc = NOW_UTC()       ' UTC time

' Current date only
today = TODAY()           ' "2025-01-22"

' Current time only
time = TIME()             ' "14:30:45"

' Unix timestamp
ts = TIMESTAMP()          ' 1737556245

Date Components

date = "2025-01-22"

year = YEAR(date)         ' Returns 2025
month = MONTH(date)       ' Returns 1
day = DAY(date)           ' Returns 22
weekday = WEEKDAY(date)   ' Returns 4 (Wednesday)
week = WEEKNUM(date)      ' Returns 4

datetime = "2025-01-22 14:30:45"
hour = HOUR(datetime)     ' Returns 14
minute = MINUTE(datetime) ' Returns 30
second = SECOND(datetime) ' Returns 45

Date Arithmetic

' Add to date
future = DATEADD("2025-01-22", 7, "day")      ' "2025-01-29"
future = DATEADD("2025-01-22", 1, "month")    ' "2025-02-22"
future = DATEADD("2025-01-22", 1, "year")     ' "2026-01-22"
future = DATEADD("2025-01-22 10:00", 2, "hour") ' "2025-01-22 12:00:00"

' Subtract from date (negative values)
past = DATEADD("2025-01-22", -7, "day")       ' "2025-01-15"

' Date difference
days = DATEDIFF("2025-01-01", "2025-01-22", "day")    ' 21
months = DATEDIFF("2025-01-01", "2025-06-01", "month") ' 5
years = DATEDIFF("2020-01-01", "2025-01-01", "year")   ' 5

Date Formatting

' Format date
formatted = FORMAT_DATE("2025-01-22", "DD/MM/YYYY")   ' "22/01/2025"
formatted = FORMAT_DATE("2025-01-22", "MMMM DD, YYYY") ' "January 22, 2025"

Date Validation

' Check if valid date
valid = ISDATE("2025-01-22")    ' true
valid = ISDATE("invalid")       ' false

End of Month

' Get last day of month
eom = EOMONTH("2025-01-15", 0)   ' "2025-01-31"
eom = EOMONTH("2025-01-15", 1)   ' "2025-02-28"
eom = EOMONTH("2025-01-15", -1)  ' "2024-12-31"

---

String Functions

Length and Substrings

' String length
length = LEN("Hello World")      ' Returns 11

' Left portion
result = LEFT("Hello World", 5)   ' Returns "Hello"

' Right portion
result = RIGHT("Hello World", 5)  ' Returns "World"

' Middle portion
result = MID("Hello World", 7)    ' Returns "World"
result = MID("Hello World", 7, 3) ' Returns "Wor"

Case Conversion

' Uppercase
result = UCASE("hello")          ' Returns "HELLO"
result = UPPER("hello")          ' Returns "HELLO"

' Lowercase
result = LCASE("HELLO")          ' Returns "hello"
result = LOWER("HELLO")          ' Returns "hello"

Trimming

' Trim whitespace
result = TRIM("  hello  ")       ' Returns "hello"
result = LTRIM("  hello")        ' Returns "hello"
result = RTRIM("hello  ")        ' Returns "hello"

Search and Replace

' Find position (1-based)
pos = INSTR("Hello World", "World")      ' Returns 7
pos = INSTR(5, "one two one", "one")     ' Returns 9 (starting from position 5)

' Replace
result = REPLACE("Hello World", "World", "Universe")  ' Returns "Hello Universe"

Split and Join

' Split string to array
parts = SPLIT("a,b,c,d", ",")    ' Returns ["a", "b", "c", "d"]

' Join array to string
arr = ["a", "b", "c"]
result = JOIN(arr, "-")          ' Returns "a-b-c"

---

Validation Functions

Type Conversion

' String to number
num = VAL("42")                  ' Returns 42.0
num = VAL("3.14")                ' Returns 3.14
num = CINT("42.7")               ' Returns 43 (rounded integer)
num = CDBL("3.14")               ' Returns 3.14

' Number to string
str = STR(42)                    ' Returns "42"
str = CSTR(3.14)                 ' Returns "3.14"

Null/Empty Checks

' Check for null
result = ISNULL(value)           ' true if null/unit

' Check for empty
result = ISEMPTY("")             ' true
result = ISEMPTY([])             ' true (empty array)
result = ISEMPTY(#{})            ' true (empty map)

Type Checks

' Check types
result = ISSTRING("hello")       ' true
result = ISNUMBER(42)            ' true
result = ISNUMBER(3.14)          ' true
result = ISBOOL(true)            ' true
result = ISARRAY([1, 2, 3])      ' true
result = ISOBJECT(#{a: 1})       ' true
result = IS_NUMERIC("42")        ' true
result = IS_DATE("2025-01-22")   ' true

' Get type name
type = TYPEOF(value)             ' Returns type name as string

Coalesce/Default Values

' Return first non-null value
result = NVL(null_value, "default")      ' Returns "default"
result = COALESCE(null_value, "default") ' Same as NVL

Conditional

' Inline if
result = IIF(score >= 70, "Pass", "Fail")

' Choose from list (1-based index)
result = CHOOSE(2, ["A", "B", "C"])  ' Returns "B"

---

Array Functions

Creating Arrays

' Create array
arr = ARRAY(1, 2, 3, 4, 5)

' Create range
arr = RANGE(1, 10)              ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
arr = RANGE(0, 10, 2)           ' [0, 2, 4, 6, 8, 10]

Array Info

' Array bounds
arr = [10, 20, 30, 40, 50]
upper = UBOUND(arr)              ' Returns 4 (last index)
lower = LBOUND(arr)              ' Returns 0 (first index)
count = COUNT(arr)               ' Returns 5 (length)

Searching

' Check if contains
result = CONTAINS(arr, 30)       ' true
result = IN_ARRAY(30, arr)       ' true (alternate syntax)

' Find index
index = INDEX_OF(arr, 30)        ' Returns 2 (-1 if not found)

Sorting

' Sort ascending
sorted = SORT(arr)

' Sort descending
sorted = SORT_DESC(arr)

Uniqueness

' Remove duplicates
arr = [1, 2, 2, 3, 3, 3]
unique = UNIQUE(arr)             ' [1, 2, 3]
unique = DISTINCT(arr)           ' Same as UNIQUE

Manipulation

' Add to end
arr = PUSH(arr, 60)

' Remove from end
last = POP(arr)

' Add to beginning
arr = UNSHIFT(arr, 0)

' Remove from beginning
first = SHIFT(arr)

' Reverse
reversed = REVERSE(arr)

' Get slice
part = SLICE(arr, 1)             ' From index 1 to end
part = SLICE(arr, 1, 3)          ' From index 1 to 3 (exclusive)

Combining

' Concatenate arrays
combined = CONCAT(arr1, arr2)

' Flatten nested arrays
nested = [[1, 2], [3, 4], [5]]
flat = FLATTEN(nested)           ' [1, 2, 3, 4, 5]

Element Access

' First and last elements
first = FIRST_ELEM(arr)
last = LAST_ELEM(arr)

---

Error Handling

Throwing Errors

' Throw an error
THROW "Something went wrong"

' Raise (alias for THROW)
RAISE "Invalid input"

Error Objects

' Create error object (for inspection)
err = ERROR("Validation failed")
' err.error = true
' err.message = "Validation failed"
' err.timestamp = "2025-01-22 14:30:45"

' Check if value is error
IF IS_ERROR(result) THEN
    msg = GET_ERROR_MESSAGE(result)
    TALK "Error occurred: " + msg
END IF

Assertions

' Assert condition
ASSERT score >= 0, "Score cannot be negative"
ASSERT NOT ISEMPTY(name), "Name is required"

' If assertion fails, throws error with message

Logging

' Log messages at different levels
LOG_ERROR "Critical failure in processing"
LOG_WARN "Unusual condition detected"
LOG_INFO "Processing completed"
LOG_DEBUG "Variable value: " + STR(x)

TRY/CATCH Pattern

While Rhai doesn't support traditional TRY...CATCH, use this pattern:

' Using error checking pattern
result = potentially_failing_operation()

IF IS_ERROR(result) THEN
    LOG_ERROR GET_ERROR_MESSAGE(result)
    result = TRY_RESULT(false, (), "Operation failed")
ELSE
    result = TRY_RESULT(true, result, "")
END IF

' result.success = true/false
' result.value = the actual value if successful
' result.error = error message if failed

---

Campaign Examples

Welcome Campaign

' Start welcome campaign for new lead
lead_email = "newuser@example.com"
lead_name = "John"

' Send immediate welcome
vars = #{name: lead_name, company: "Acme"}
SEND TEMPLATE "welcome-email-1", "email", lead_email, vars

' Schedule follow-ups
SET SCHEDULE DATEADD(TODAY(), 2, "day"), "send-welcome-2.bas"
SET SCHEDULE DATEADD(TODAY(), 5, "day"), "send-welcome-3.bas"
SET SCHEDULE DATEADD(TODAY(), 14, "day"), "send-welcome-final.bas"

' Score the lead
score = SCORE LEAD #{email: lead_email, name: lead_name}
TALK "Welcome campaign started. Initial score: " + score.score

Social Media Campaign

' Product launch social media campaign
product_name = "AI Assistant Pro"
launch_date = "2025-02-15"

' Generate image
product_image = IMAGE "Product launch graphic for " + product_name

' Schedule posts across platforms
hashtags = "#AI #Automation #NewProduct"

' Day -7: Teaser
POST TO "instagram,facebook,linkedin" AT DATEADD(launch_date, -7, "day") + " 10:00" product_image, "Something big is coming... 🔥 " + hashtags

' Day -3: Feature preview  
POST TO "instagram,twitter" AT DATEADD(launch_date, -3, "day") + " 10:00" product_image, "Sneak peek! " + hashtags

' Launch day
POST TO "instagram,facebook,twitter,linkedin" AT launch_date + " 09:00" product_image, "🚀 IT'S HERE! " + product_name + " is now LIVE! " + hashtags

TALK "Social media campaign scheduled with " + 6 + " posts"

Lead Nurturing with AI Scoring

' Process form submission
ON FORM SUBMIT "landing-page"
    ' Extract data
    lead = #{
        email: fields.email,
        name: fields.name,
        company: fields.company,
        job_title: fields.title,
        industry: fields.industry
    }
    
    ' AI-powered scoring
    score = AI SCORE LEAD lead
    
    ' Route based on score
    IF score.score >= 85 THEN
        ' Hot lead - immediate action
        CREATE TASK "Contact hot lead: " + lead.email, "sales", "high"
        SEND TEMPLATE "hot-lead-welcome", "email,sms", lead.email, lead
    ELSE IF score.score >= 70 THEN
        ' Warm lead - accelerated nurture
        SEND TEMPLATE "warm-welcome", "email", lead.email, lead
        SET SCHEDULE DATEADD(NOW(), 3, "day"), "warm-nurture-2.bas"
    ELSE
        ' Cold lead - standard drip
        SEND TEMPLATE "cold-welcome", "email", lead.email, lead
        SET SCHEDULE DATEADD(NOW(), 7, "day"), "cold-nurture-2.bas"
    END IF
    
    ' Save to CRM
    SAVE "leads", lead.email, lead.name, score.score, score.grade, NOW()
END ON

---

Configuration

Social Media Credentials

Store in bot_settings table:

• instagram_credentials: {access_token, user_id}
• facebook_credentials: {access_token, page_id}
• linkedin_credentials: {access_token, person_urn}
• twitter_credentials: {bearer_token}

Lead Scoring Weights

Default weights (customizable per bot):

Factor	Default Weight
Company Size	10
Industry Match	15
Job Title	15
Location	5
Email Opens	5
Email Clicks	10
Page Visits	5
Form Submissions	15
Content Downloads	10
Pricing Page Visits	20
Demo Requests	25
Trial Signups	30
Inactivity Penalty	-15

---

Last updated: January 2025 General Bots v5.0