Quick Reference Cheatsheet

Fast lookup for WooAI Chatbot Pro developers. Keep this open while coding.

Why this exists: After the 3rd time someone asked “where’s that hook again?”,
I made this. Update it when you add new stuff. – Roman

---

REST API Endpoints

# Base URL
/wp-json/woo-ai/v1/

# Chat
POST /chat/session              # Create session
POST /chat/message              # Send message
GET  /chat/session?session_id={id} # Get session + message history

# Playbooks
GET    /playbooks               # List all
GET    /playbooks/{id}          # Get one
POST   /playbooks               # Create
PUT    /playbooks/{id}          # Update
DELETE /playbooks/{id}          # Delete

# Settings
GET  /settings                  # Get all
POST /settings                  # Update

# Analytics
GET /analytics/summary          # Dashboard summary
GET /analytics/conversations    # Conversation stats

# Topics
GET  /public/topics             # Public (no auth)
GET  /topics                    # Admin list
POST /topics                    # Create/update

---

Key Hooks

Actions

// AI Processing
do_action( 'wooai_before_ai_request', $provider, $messages );
do_action( 'wooai_after_ai_response', $response, $provider );
do_action( 'wooai_provider_fallback', $failed, $next, $error );

// Chat
do_action( 'wooai_session_started', $session_id, $user_id );
do_action( 'wooai_message_received', $message, $session_id );
do_action( 'wooai_message_sent', $response, $session_id );

// Playbook
do_action( 'wooai_playbook_started', $playbook_id, $session_id );
do_action( 'wooai_playbook_step_execute', $step, $state );
do_action( 'wooai_playbook_completed', $playbook_id, $session_id );

// Widget
do_action( 'wooai_before_widget_render' );
do_action( 'wooai_after_widget_render' );

Filters

// AI
add_filter( 'wooai_ai_response', fn($r) => $r );
add_filter( 'wooai_system_prompt', fn($p) => $p );
add_filter( 'wooai_provider_priority', fn($p) => $p );
add_filter( 'wooai_max_tokens', fn() => 2000 );

// Chat
add_filter( 'wooai_message_before_save', fn($m) => $m );
add_filter( 'wooai_suggestions', fn($s, $ctx) => $s, 10, 2 );

// Widget
add_filter( 'wooai_widget_should_display', fn($show) => $show );
add_filter( 'wooai_widget_position', fn() => 'bottom-right' );
add_filter( 'wooai_widget_config', fn($c) => $c );

// Rate Limiting
add_filter( 'wooai_rate_limit', fn() => 30 );  // requests
add_filter( 'wooai_rate_window', fn() => 60 ); // seconds

---

PHP Classes

// Singletons - use ::instance()
WooAIChatbotPlugin::instance()
WooAIChatbotAIAIOrchestrator::instance()
WooAIChatbotAIToolRegistry::instance()

// AI Providers
WooAIChatbotAIProvidersOpenAIProvider
WooAIChatbotAIProvidersClaudeProvider
WooAIChatbotAIProvidersGeminiProvider

// Chat
WooAIChatbotChatMessageHandler
WooAIChatbotChatSessionManager
WooAIChatbotChatWidget

// Playbook (WooAI namespace)
WooAIPlaybookPlaybookEngine
WooAIPlaybookPlaybookRepository
WooAIPlaybookPlaybookStateManager

// Search
WooAIChatbotSearchSemanticSearch
WooAIChatbotSearchProductIndexer

---

TypeScript Types

// Message
interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  metadata?: MessageMetadata;
  timestamp: string;
}

// Session
interface ChatSession {
  session_id: string;
  user_id?: number;
  started_at: string;
  messages: Message[];
}

// Playbook Step
interface PlaybookStep {
  id: string;
  type: 'message' | 'question' | 'options' | 'product_list' | 'coupon' | 'link';
  content: string;
  options?: StepOption[];
  next?: string | null;
}

// Settings
interface PluginSettings {
  enabled: boolean;
  ai_provider: 'openai' | 'claude' | 'gemini';
  model: string;
  temperature: number;
  appearance: AppearanceSettings;
}

---

NPM Scripts

npm run dev          # Dev build + watch
npm run build        # Production build
npm run typecheck    # TS check
npm run lint         # ESLint fix
npm run test         # Jest
npm run test:coverage

Composer Scripts

composer test        # PHPUnit
composer phpcs       # Code sniffer
composer phpcbf      # Auto-fix

---

Database Tables

-- Conversations
{prefix}wooai_conversations (
  id, session_id, user_id, started_at, updated_at, metadata
)

-- Messages
{prefix}wooai_messages (
  id, conversation_id, role, content, tokens, created_at
)

-- Analytics
{prefix}wooai_analytics (
  id, event_type, session_id, user_id, data, created_at
)

---

Common Patterns

Add Custom Tool

add_action( 'wooai_register_tools', function( $registry ) {
    $registry->register( new class implements ToolInterface {
        public function get_name(): string { return 'my_tool'; }
        public function get_description(): string { return 'Does something'; }
        public function get_parameters(): array { return []; }
        public function execute( array $args ): array {
            return [ 'result' => 'done' ];
        }
    });
});

Modify AI Response

add_filter( 'wooai_ai_response', function( $response, $messages, $context ) {
    $response['content'] .= "nn---nPowered by AI";
    return $response;
}, 10, 3 );

Custom Widget Position

add_filter( 'wooai_widget_config', function( $config ) {
    $config['position'] = 'bottom-left';
    $config['offset'] = [ 'x' => 20, 'y' => 20 ];
    return $config;
});

Exclude Pages

add_filter( 'wooai_widget_should_display', function( $show ) {
    if ( is_cart() || is_checkout() ) return false;
    if ( is_page( 'contact' ) ) return false;
    return $show;
});

Custom Analytics Event

do_action( 'wooai_track_event', 'custom_event', [
    'session_id' => $session_id,
    'data' => [ 'key' => 'value' ]
]);

---

Debug Mode

// wp-config.php
define( 'WOOAI_DEBUG', true );
define( 'WOOAI_LOG_AI_REQUESTS', true );

// Browser console
localStorage.setItem('wooai_debug', 'true');

---

Error Codes

Code	HTTP	Meaning
invalid_session	404	Session expired/not found
rate_limit_exceeded	429	Too many requests
ai_provider_error	500	API call failed
validation_error	400	Bad request data
permission_denied	403	Missing capability

Known Gotchas

// GOTCHA #1: Session ID format changed in 0.2.0
// Old: "abc123" (short)
// New: "usr42-1703980123-x7f2" (user-timestamp-random)
// Some old sessions may still exist in DB - we don't migrate them

// GOTCHA #2: Widget won't appear if theme missing wp_footer()
// Spent 2 hours debugging flavflavor theme - this was the issue

// GOTCHA #3: Gemini sometimes returns empty content
// We retry 3x automatically, see class-gemini-provider.php:147

---

File Locations

/includes/class-plugin.php       # Main entry
/includes/AI/                    # AI providers
/includes/chat/                  # Chat engine
/includes/playbook/              # Playbook system
/assets/src/admin/               # Admin React
/assets/src/chat/                # Widget React
/assets/dist/                    # Built assets

---

Useful WP-CLI

# Clear plugin transients
wp transient delete --all

# Check option
wp option get woo_ai_chatbot_settings --format=json

# Reset settings
wp option delete woo_ai_chatbot_settings

# Test API
wp eval "var_dump(WooAIChatbotAIAIOrchestrator::instance()->validate_current_provider());"