botserver/docs/HEAR_VALIDATION_REFERENCE.md

HEAR Keyword - Input Validation Reference

Complete reference for HEAR keyword with automatic input validation in General Bots BASIC

Overview

The HEAR keyword waits for user input with optional automatic validation. When using HEAR AS <TYPE>, the system will:

1. Wait for user input
2. Validate against the specified type
3. Automatically retry with a helpful error message if invalid
4. Return the normalized/parsed value once valid

This eliminates the need for manual validation loops and provides a consistent, user-friendly experience.

---

Table of Contents

1. Basic HEAR
2. Text Validation Types
3. Numeric Types
4. Date/Time Types
5. Brazilian Document Types
6. Contact Types
7. Menu Selection
8. Media Types
9. Authentication Types
10. Examples
11. Best Practices

---

Basic HEAR

' Simple HEAR without validation - accepts any input
HEAR response
TALK "You said: " + response

---

Text Validation Types

HEAR AS EMAIL

Validates email address format and normalizes to lowercase.

TALK "What's your email address?"
HEAR email AS EMAIL
TALK "We'll send confirmation to: " + email

Validation:

• Must contain @ symbol
• Must have valid domain format
• Normalized to lowercase

Error message: "Please enter a valid email address (e.g., user@example.com)"

---

HEAR AS NAME

Validates name format (letters, spaces, hyphens, apostrophes).

TALK "What's your full name?"
HEAR name AS NAME
TALK "Nice to meet you, " + name + "!"

Validation:

• Minimum 2 characters
• Maximum 100 characters
• Only letters, spaces, hyphens, apostrophes
• Auto-capitalizes first letter of each word

Error message: "Please enter a valid name (letters and spaces only)"

---

HEAR AS URL

Validates and normalizes URL format.

TALK "Enter your website URL:"
HEAR website AS URL
TALK "I'll check " + website

Validation:

• Valid URL format
• Auto-adds https:// if protocol missing

Error message: "Please enter a valid URL"

---

HEAR AS PASSWORD

Validates password strength (minimum requirements).

TALK "Create a password (minimum 8 characters):"
HEAR password AS PASSWORD
' Returns "[PASSWORD SET]" - actual password stored securely

Validation:

• Minimum 8 characters
• Returns strength indicator (weak/medium/strong)
• Never echoes the actual password

Error message: "Password must be at least 8 characters"

---

HEAR AS COLOR

Validates and normalizes color values.

TALK "Pick a color:"
HEAR color AS COLOR
TALK "You selected: " + color  ' Returns hex format like #FF0000

Accepts:

• Named colors: "red", "blue", "green", etc.
• Hex format: "#FF0000" or "FF0000"
• RGB format: "rgb(255, 0, 0)"

Returns: Normalized hex format (#RRGGBB)

---

HEAR AS UUID

Validates UUID/GUID format.

TALK "Enter the transaction ID:"
HEAR transaction_id AS UUID

---

Numeric Types

HEAR AS INTEGER

Validates and parses integer numbers.

TALK "How old are you?"
HEAR age AS INTEGER
TALK "In 10 years you'll be " + STR(age + 10)

Validation:

• Accepts whole numbers only
• Removes formatting (commas, spaces)
• Returns numeric value

Error message: "Please enter a valid whole number"

---

HEAR AS FLOAT / DECIMAL

Validates and parses decimal numbers.

TALK "Enter the temperature:"
HEAR temperature AS FLOAT
TALK "Temperature is " + STR(temperature) + "°C"

Validation:

• Accepts decimal numbers
• Handles both . and , as decimal separator
• Returns numeric value rounded to 2 decimal places

---

HEAR AS MONEY / CURRENCY / AMOUNT

Validates and normalizes monetary amounts.

TALK "How much would you like to transfer?"
HEAR amount AS MONEY
TALK "Transferring R$ " + FORMAT(amount, "#,##0.00")

Accepts:

• "100"
• "100.00"
• "1,234.56" (US format)
• "1.234,56" (Brazilian/European format)
• "R$ 100,00"
• "$100.00"

Returns: Normalized decimal value (e.g., "1234.56")

Error message: "Please enter a valid amount (e.g., 100.00 or R$ 100,00)"

---

HEAR AS CREDITCARD / CARD

Validates credit card number using Luhn algorithm.

TALK "Enter your card number:"
HEAR card AS CREDITCARD
' Returns masked format: "4111 **** **** 1111"

Validation:

• 13-19 digits
• Passes Luhn checksum
• Detects card type (Visa, Mastercard, Amex, etc.)

Returns: Masked card number with metadata about card type

---

Date/Time Types

HEAR AS DATE

Validates and parses date input.

TALK "When is your birthday?"
HEAR birthday AS DATE
TALK "Your birthday is " + FORMAT(birthday, "MMMM d")

Accepts multiple formats:

• "25/12/2024" (DD/MM/YYYY)
• "12/25/2024" (MM/DD/YYYY)
• "2024-12-25" (ISO format)
• "25 Dec 2024"
• "December 25, 2024"
• "today", "tomorrow", "yesterday"
• "hoje", "amanhã", "ontem" (Portuguese)

Returns: Normalized ISO date (YYYY-MM-DD)

Error message: "Please enter a valid date (e.g., 25/12/2024 or 2024-12-25)"

---

HEAR AS HOUR / TIME

Validates and parses time input.

TALK "What time should we schedule the meeting?"
HEAR meeting_time AS HOUR
TALK "Meeting scheduled for " + meeting_time

Accepts:

• "14:30" (24-hour format)
• "2:30 PM" (12-hour format)
• "14:30:00" (with seconds)

Returns: Normalized 24-hour format (HH:MM)

Error message: "Please enter a valid time (e.g., 14:30 or 2:30 PM)"

---

Brazilian Document Types

HEAR AS CPF

Validates Brazilian CPF (individual taxpayer ID).

TALK "Enter your CPF:"
HEAR cpf AS CPF
TALK "CPF validated: " + cpf  ' Returns formatted: 123.456.789-09

Validation:

• 11 digits
• Valid check digits (mod 11 algorithm)
• Rejects known invalid patterns (all same digit)

Returns: Formatted CPF (XXX.XXX.XXX-XX)

Error message: "Please enter a valid CPF (11 digits)"

---

HEAR AS CNPJ

Validates Brazilian CNPJ (company taxpayer ID).

TALK "Enter your company's CNPJ:"
HEAR cnpj AS CNPJ
TALK "CNPJ validated: " + cnpj  ' Returns formatted: 12.345.678/0001-95

Validation:

• 14 digits
• Valid check digits

Returns: Formatted CNPJ (XX.XXX.XXX/XXXX-XX)

Error message: "Please enter a valid CNPJ (14 digits)"

---

Contact Types

HEAR AS MOBILE / PHONE / TELEPHONE

Validates phone number format.

TALK "What's your phone number?"
HEAR phone AS MOBILE
TALK "We'll send SMS to: " + phone

Validation:

• 10-15 digits
• Auto-formats based on detected country

Returns: Formatted phone number

Error message: "Please enter a valid mobile number"

---

HEAR AS ZIPCODE / CEP / POSTALCODE

Validates postal code format.

TALK "What's your ZIP code?"
HEAR cep AS ZIPCODE
TALK "Your ZIP code is: " + cep

Supports:

• Brazilian CEP: 8 digits → "12345-678"
• US ZIP: 5 or 9 digits → "12345" or "12345-6789"
• UK postcode: alphanumeric → "SW1A 1AA"

Returns: Formatted postal code with country detection

---

Menu Selection

HEAR AS "Option1", "Option2", "Option3"

Presents a menu and validates selection.

TALK "Choose your preferred fruit:"
HEAR fruit AS "Apple", "Banana", "Orange", "Mango"
TALK "You selected: " + fruit

Accepts:

• Exact match: "Apple"
• Case-insensitive: "apple"
• Numeric selection: "1", "2", "3"
• Partial match: "app" → "Apple" (if unique)

Automatically adds suggestions for the menu options.

Error message: "Please select one of: Apple, Banana, Orange, Mango"

---

HEAR AS BOOLEAN

Validates yes/no response.

TALK "Do you agree to the terms?"
HEAR agreed AS BOOLEAN
IF agreed THEN
    TALK "Thank you for agreeing!"
ELSE
    TALK "You must agree to continue."
END IF

Accepts (true): "yes", "y", "true", "1", "sim", "ok", "sure", "confirm"

Accepts (false): "no", "n", "false", "0", "não", "cancel", "deny"

Returns: "true" or "false" (with boolean metadata)

Error message: "Please answer yes or no"

---

HEAR AS LANGUAGE

Validates language code or name.

TALK "What language do you prefer?"
HEAR language AS LANGUAGE
SET CONTEXT LANGUAGE language
TALK "Language set to: " + language

Accepts:

• ISO codes: "en", "pt", "es", "fr", "de"
• Full names: "English", "Portuguese", "Spanish"
• Native names: "Português", "Español", "Français"

Returns: ISO 639-1 language code

---

Media Types

HEAR AS IMAGE / PHOTO / PICTURE

Waits for image upload.

TALK "Please send a photo of your document:"
HEAR document_photo AS IMAGE
TALK "Image received: " + document_photo
' Returns URL to the uploaded image

Validation:

• Must receive image attachment
• Accepts: JPG, PNG, GIF, WebP

Error message: "Please send an image"

---

HEAR AS QRCODE

Waits for image with QR code and reads it.

TALK "Send me a photo of the QR code:"
HEAR qr_data AS QRCODE
TALK "QR code contains: " + qr_data

Process:

1. Waits for image upload
2. Calls BotModels vision API to decode QR
3. Returns the decoded data

Error message: "Please send an image containing a QR code"

---

HEAR AS AUDIO / VOICE / SOUND

Waits for audio input and transcribes to text.

TALK "Send me a voice message:"
HEAR transcription AS AUDIO
TALK "You said: " + transcription

Process:

1. Waits for audio attachment
2. Calls BotModels speech-to-text API
3. Returns transcribed text

Error message: "Please send an audio file or voice message"

---

HEAR AS VIDEO

Waits for video upload and describes content.

TALK "Send a video of the problem:"
HEAR video_description AS VIDEO
TALK "I can see: " + video_description

Process:

1. Waits for video attachment
2. Calls BotModels vision API to describe
3. Returns AI-generated description

Error message: "Please send a video"

---

HEAR AS FILE / DOCUMENT / DOC / PDF

Waits for document upload.

TALK "Please upload your contract:"
HEAR contract AS DOCUMENT
TALK "Document received: " + contract

Accepts: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV

Returns: URL to the uploaded file

---

Authentication Types

HEAR AS LOGIN

Waits for Active Directory/OAuth login completion.

TALK "Please click the link to authenticate:"
HEAR user AS LOGIN
TALK "Welcome, " + user.name + "!"

Process:

1. Generates authentication URL
2. Waits for OAuth callback
3. Returns user object with tokens

---

Examples

Complete Registration Flow

TALK "Let's create your account!"

TALK "What's your full name?"
HEAR name AS NAME

TALK "Enter your email address:"
HEAR email AS EMAIL

TALK "Enter your CPF:"
HEAR cpf AS CPF

TALK "What's your phone number?"
HEAR phone AS MOBILE

TALK "Choose a password:"
HEAR password AS PASSWORD

TALK "What's your birth date?"
HEAR birthdate AS DATE

TALK "Select your gender:"
HEAR gender AS "Male", "Female", "Other", "Prefer not to say"

' All inputs are now validated and normalized
TALK "Creating account for " + name + "..."

TABLE new_user
    ROW name, email, cpf, phone, birthdate, gender, NOW()
END TABLE
SAVE "users.csv", new_user

TALK "✅ Account created successfully!"

Payment Flow

TALK "💳 Let's process your payment"

TALK "Enter the amount:"
HEAR amount AS MONEY

IF amount < 1 THEN
    TALK "Minimum payment is R$ 1.00"
    RETURN
END IF

TALK "How would you like to pay?"
HEAR method AS "Credit Card", "Debit Card", "PIX", "Boleto"

IF method = "PIX" THEN
    TALK "Enter the PIX key (phone, email, or CPF):"
    ' Note: We could create HEAR AS PIX_KEY if needed
    HEAR pix_key
ELSEIF method = "Boleto" THEN
    TALK "Enter the barcode (47-48 digits):"
    HEAR barcode AS INTEGER
END IF

TALK "Confirm payment of R$ " + FORMAT(amount, "#,##0.00") + "?"
HEAR confirm AS BOOLEAN

IF confirm THEN
    TALK "✅ Processing payment..."
ELSE
    TALK "Payment cancelled."
END IF

Customer Support with Media

TALK "How can I help you today?"
HEAR issue AS "Report a bug", "Request feature", "Billing question", "Other"

IF issue = "Report a bug" THEN
    TALK "Please describe the problem:"
    HEAR description
    
    TALK "Can you send a screenshot of the issue?"
    HEAR screenshot AS IMAGE
    
    TALK "Thank you! We've logged your bug report."
    TALK "Reference: BUG-" + FORMAT(NOW(), "yyyyMMddHHmmss")
    
ELSEIF issue = "Billing question" THEN
    TALK "Please upload your invoice or send the transaction ID:"
    HEAR reference
END IF

---

Best Practices

1. Always Use Appropriate Types

' ❌ Bad - no validation
HEAR email
IF NOT email CONTAINS "@" THEN
    TALK "Invalid email"
    ' Need to implement retry logic...
END IF

' ✅ Good - automatic validation and retry
HEAR email AS EMAIL
' Guaranteed to be valid when we get here

2. Combine with Context

SET CONTEXT "You are a helpful banking assistant. 
When asking for monetary values, always confirm before processing."

TALK "How much would you like to withdraw?"
HEAR amount AS MONEY
' LLM and validation work together

3. Use Menu for Limited Options

' ❌ Bad - open-ended when options are known
HEAR payment_method
IF payment_method <> "credit" AND payment_method <> "debit" THEN
    ' Handle unknown input...
END IF

' ✅ Good - constrained to valid options
HEAR payment_method AS "Credit Card", "Debit Card", "PIX"

4. Provide Context Before HEAR

' ❌ Bad - no context
HEAR value AS MONEY

' ✅ Good - user knows what to enter
TALK "Enter the transfer amount (minimum R$ 1.00):"
HEAR amount AS MONEY

5. Use HEAR AS for Security-Sensitive Data

' CPF is automatically validated
HEAR cpf AS CPF

' Credit card passes Luhn check and is masked
HEAR card AS CREDITCARD

' Password never echoed back
HEAR password AS PASSWORD

---

Error Handling

Validation errors are handled automatically, but you can customize:

' The system automatically retries up to 3 times
' After 3 failures, execution continues with empty value

' You can check if validation succeeded:
HEAR email AS EMAIL
IF email = "" THEN
    TALK "Unable to validate email after multiple attempts."
    TALK "Please contact support for assistance."
    RETURN
END IF

---

Metadata Access

Some validation types provide additional metadata:

HEAR card AS CREDITCARD
' card = "**** **** **** 1234"
' Metadata available: card_type, last_four

HEAR date AS DATE
' date = "2024-12-25"
' Metadata available: original input, parsed format

HEAR audio AS AUDIO
' audio = "transcribed text here"
' Metadata available: language, confidence

---

Integration with BotModels

Media types (QRCODE, AUDIO, VIDEO) automatically call BotModels services:

Type	BotModels Endpoint	Service
QRCODE	/api/v1/vision/qrcode	QR Code detection
AUDIO	/api/v1/speech/to-text	Whisper transcription
VIDEO	/api/v1/vision/describe-video	BLIP2 video description
IMAGE (with question)	/api/v1/vision/vqa	Visual Q&A

Configure BotModels URL in config.csv:

botmodels-url,http://localhost:8001
botmodels-enabled,true

---

Summary Table

Type	Example Input	Normalized Output
EMAIL	"User@Example.COM"	"user@example.com"
NAME	"john DOE"	"John Doe"
INTEGER	"1,234"	1234
MONEY	"R$ 1.234,56"	"1234.56"
DATE	"25/12/2024"	"2024-12-25"
HOUR	"2:30 PM"	"14:30"
BOOLEAN	"yes" / "sim"	"true"
CPF	"12345678909"	"123.456.789-09"
MOBILE	"11999998888"	"(11) 99999-8888"
CREDITCARD	"4111111111111111"	"4111 **** **** 1111"
QRCODE	[image]	"decoded QR data"
AUDIO	[audio file]	"transcribed text"

---

HEAR AS validation - Making input handling simple, secure, and user-friendly.