REST API Reference

WooAI Chatbot Pro provides a comprehensive REST API for integrating chatbot functionality, managing configurations, and accessing analytics data. This reference documents all available endpoints, authentication requirements, request/response schemas, and usage examples.

Heads up: If you're getting 401 errors, check the nonce first. 9 times out of 10 it's a caching plugin storing the old nonce. WP Rocket, LiteSpeed Cache - all of them. See Troubleshooting #3 for the fix.

1. API Overview

Base URL Structure

All API endpoints are registered under the WordPress REST API namespace:

https://your-site.com/wp-json/woo-ai/v1/{endpoint}

Namespaces

The legacy namespace (woo-ai-chatbot/v1) remains functional for existing integrations but will be removed in a future major release. All new implementations should use woo-ai/v1.

Authentication

The API supports two authentication patterns based on endpoint access level:

Public Endpoints (no authentication required):

• GET /public/topics - Retrieve enabled topics for widget display
• POST /public/topics/contextual - Get context-filtered topics

Protected Endpoints require one of the following:

1. WordPress Nonce (frontend JavaScript):

   fetch('/wp-json/woo-ai/v1/chat/message', {
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
           'X-WP-Nonce': wooAiChatbot.nonce
       },
       body: JSON.stringify({ session_id: '...', message: '...' })
   });
   

2. Cookie Authentication (logged-in WordPress users): Automatic when making requests from the same domain with valid WordPress cookies.

3. Application Passwords (external integrations): WordPress 5.6+ application passwords for external API consumers.

Rate Limiting

Chat endpoints implement rate limiting to prevent abuse:

When rate limit is exceeded, the API returns:

{
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait a moment and try again.",
    "data": { "status": 429 }
}

Permission Requirements

2. Chat Endpoints

Chat endpoints handle real-time messaging, session lifecycle, and WooCommerce cart operations.

POST /chat/message

Send a user message to the AI chatbot and receive a response.

Request:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/message" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "session_id": "abc123-def456-ghi789",
    "message": "What products do you recommend for outdoor activities?"
  }'

Parameters:

Response (200 OK):

{
    "success": true,
    "session_id": "abc123-def456-ghi789",
    "message": {
        "role": "assistant",
        "content": "I'd recommend checking out our hiking boots and camping gear collection!",
        "metadata": {
            "products": [
                {
                    "id": 123,
                    "name": "Trail Master Hiking Boots",
                    "price": "89.99",
                    "price_html": "<span class=\"woocommerce-Price-amount\">$89.99</span>",
                    "image": "https://example.com/boots.jpg",
                    "url": "https://example.com/product/hiking-boots/",
                    "in_stock": true
                }
            ],
            "suggestions": ["View all outdoor gear", "Check delivery options"]
        }
    },
    "products": [...],
    "suggestions": [...],
    "type": "product_recommendation",
    "intent": "product_search"
}

Error Responses:

GET /chat/session

Retrieve session data including conversation history and context.

Request:

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/chat/session?session_id=abc123-def456-ghi789" \
  -H "X-WP-Nonce: your_nonce_here"

Response (200 OK):

{
    "success": true,
    "session": {
        "session_id": "abc123-def456-ghi789",
        "conversation_history": [
            { "role": "user", "content": "Hello" },
            { "role": "assistant", "content": "Welcome! How can I help?" }
        ],
        "context": {
            "cart": { "items": [], "total": "0.00" },
            "current_product": null,
            "recently_viewed": []
        },
        "created_at": "2024-01-15T10:30:00Z",
        "expires_at": "2024-01-15T11:30:00Z"
    }
}

POST /chat/session

Create a new chat session. Sessions expire after 1 hour by default.

Request:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/session" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "user_id": 42 }'

Parameters:

Response (201 Created):

{
    "success": true,
    "session_id": "abc123-def456-ghi789",
    "expires_at": "2024-01-15T11:30:00Z"
}

DELETE /chat/session/{id}

Terminate an active chat session.

Request:

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/chat/session/abc123-def456-ghi789" \
  -H "X-WP-Nonce: your_nonce_here"

Response (200 OK):

{
    "success": true,
    "message": "Session ended successfully."
}

POST /chat/events

Track analytics events from the chat widget.

Request:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/events" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "sessionId": "abc123-def456-ghi789",
    "eventType": "product_click",
    "eventData": { "product_id": 123, "position": 1 },
    "timestamp": 1705312200000
  }'

Response (200 OK):

{
    "success": true,
    "message": "Event tracked successfully."
}

Cart Operations

POST /cart/add

Add a product to the WooCommerce cart.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/add" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "product_id": 123,
    "quantity": 2,
    "variation_id": 456,
    "variation": { "attribute_color": "blue" }
  }'

GET /cart

Retrieve current cart contents.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/cart" \
  -H "X-WP-Nonce: your_nonce_here"

DELETE /cart

Clear the entire cart.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/cart" \
  -H "X-WP-Nonce: your_nonce_here"

DELETE /cart/item/{key}

Remove a specific item from the cart.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/cart/item/abc123def456" \
  -H "X-WP-Nonce: your_nonce_here"

PUT /cart/item/{key}

Update cart item quantity.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/cart/item/abc123def456" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "quantity": 3 }'

POST /cart/coupon

Apply a coupon code to the cart.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/coupon" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "coupon_code": "SAVE20" }'

POST /cart/checkout

Get checkout URL with optional parameters.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/checkout" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "params": { "source": "chatbot" } }'

Response:

{
    "success": true,
    "checkout_url": "https://your-site.com/checkout/?source=chatbot"
}

3. Analytics Endpoints

Analytics endpoints provide KPIs, performance metrics, and data export capabilities.

GET /analytics

Retrieve full analytics dashboard data.

Request:

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

Parameters:

Response (200 OK):

{
    "kpis": {
        "total_sessions": 1250,
        "total_messages": 4320,
        "avg_messages_per_session": 3.45,
        "conversion_rate": 8.5,
        "product_clicks": 890,
        "add_to_cart_count": 234
    },
    "topProducts": [
        {
            "id": 123,
            "name": "Premium Widget",
            "mentions": 156,
            "clicks": 89,
            "conversionRate": 12.5
        }
    ],
    "chartData": [
        { "hour": "00:00", "value": 12 },
        { "hour": "01:00", "value": 8 }
    ],
    "dateRange": {
        "from": "2024-01-01",
        "to": "2024-01-31"
    }
}

GET /analytics/summary

Retrieve KPI summary only (lightweight endpoint).

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/summary?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/topics

Retrieve topic performance metrics.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/topics?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "topics": [
        {
            "slug": "shipping_delivery",
            "name": "Shipping & Delivery",
            "count": 342,
            "percentage": 28.5
        }
    ],
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/products

Retrieve product performance metrics.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/products?from=2024-01-01&to=2024-01-31&limit=10" \
  -H "X-WP-Nonce: your_nonce_here"

Parameters:

GET /analytics/funnel

Retrieve conversion funnel data.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/funnel?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "funnel": {
        "sessions": 1250,
        "engaged_sessions": 980,
        "product_views": 654,
        "add_to_cart": 234,
        "checkouts": 156,
        "purchases": 89
    },
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/hourly

Retrieve hourly activity distribution.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/hourly?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "hourly": [
        { "hour": "00:00", "count": 45 },
        { "hour": "01:00", "count": 23 }
    ],
    "raw": {
        "0": 45, "1": 23, "2": 12
    },
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/queries

Retrieve top user queries.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/queries?from=2024-01-01&to=2024-01-31&limit=10" \
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/comparison

Retrieve week-over-week comparison.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/comparison" \
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/export

Export analytics data as CSV.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/export?from=2024-01-01&to=2024-01-31" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "csv": "date,sessions,messages,conversions\n2024-01-01,45,123,5\n...",
    "filename": "analytics-2024-01-01-2024-01-31.csv",
    "mimeType": "text/csv"
}

POST /analytics/events

Track a custom analytics event.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/analytics/events" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "event": "custom_action",
    "data": { "action": "feature_used", "value": "quick_reply" }
  }'

POST /analytics/cache/clear

Clear the analytics cache.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/analytics/cache/clear" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "success": true,
    "deletedCount": 24,
    "message": "Cleared 24 cache entries."
}

4. Playbook Endpoints

Playbooks define automated conversation flows and actions.

GET /playbooks

List all playbooks with optional filtering.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/playbooks?status=active&per_page=20&orderby=priority&order=DESC" \
  -H "X-WP-Nonce: your_nonce_here"

Parameters:

Response (200 OK):

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Return Policy",
            "intent": "returns",
            "priority": 10,
            "steps": [...],
            "conditions": [...],
            "trigger": "auto",
            "status": "active",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-16T14:22:00Z"
        }
    ],
    "count": 6
}

POST /playbooks

Create a new playbook.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "name": "Shipping Information",
    "intent": "shipping_query",
    "priority": 8,
    "trigger": "auto",
    "steps": [
        {
            "id": "step_1",
            "type": "message",
            "content": "We offer free shipping on orders over $50!",
            "next_step": "step_2"
        },
        {
            "id": "step_2",
            "type": "options",
            "content": "Would you like more details?",
            "options": [
                { "label": "Delivery times", "value": "delivery" },
                { "label": "Track order", "value": "tracking" }
            ]
        }
    ],
    "conditions": [
        { "type": "cart_total", "operator": "less_than", "value": 50 }
    ]
  }'

Playbook Schema:

Step Types:

Response (201 Created):

{
    "success": true,
    "data": { ... },
    "message": "Playbook created successfully."
}

GET /playbooks/{id}

Retrieve a single playbook by ID.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" \
  -H "X-WP-Nonce: your_nonce_here"

PUT /playbooks/{id}

Update an existing playbook.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "name": "Updated Shipping Info",
    "priority": 9
  }'

DELETE /playbooks/{id}

Delete a playbook permanently.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" \
  -H "X-WP-Nonce: your_nonce_here"

POST /playbooks/{id}/duplicate

Create a copy of an existing playbook.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks/1/duplicate" \
  -H "X-WP-Nonce: your_nonce_here"

POST /playbooks/{id}/toggle

Toggle playbook between active and draft status.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks/1/toggle" \
  -H "X-WP-Nonce: your_nonce_here"

5. Topics Endpoints

Topics categorize conversation intents for routing and analytics.

Admin Endpoints (Require manage_woocommerce)

GET /topics

List all topics.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/topics" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

[
    {
        "id": "shipping_delivery",
        "slug": "shipping_delivery",
        "name": "Shipping & Delivery",
        "description": "Shipping methods, delivery times, tracking",
        "icon": "truck",
        "keywords": ["shipping", "delivery", "tracking"],
        "patterns": ["when.*arrive", "track.*order"],
        "priority": 7,
        "enabled": true,
        "detection_methods": ["keyword", "intent", "context"],
        "questions": 28,
        "usage": 87
    }
]

POST /topics

Create a new topic.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/topics" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "slug": "gift_wrapping",
    "name": "Gift Wrapping",
    "description": "Gift wrap options and pricing",
    "keywords": ["gift", "wrap", "wrapping", "present"],
    "patterns": ["gift.*wrap", "wrap.*present"],
    "priority": 5,
    "enabled": true,
    "detection_methods": ["keyword", "intent"]
  }'

PUT /topics/{id}

Update an existing topic.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/topics/gift_wrapping" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "priority": 6,
    "enabled": true
  }'

DELETE /topics/{id}

Delete a topic.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/topics/gift_wrapping" \
  -H "X-WP-Nonce: your_nonce_here"

POST /topics/{id}/toggle

Toggle topic enabled status.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/topics/shipping_delivery/toggle" \
  -H "X-WP-Nonce: your_nonce_here"

Public Endpoints (No Authentication)

GET /public/topics

Retrieve all enabled topics for widget display.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/public/topics"

Response:

[
    {
        "id": "shipping_delivery",
        "slug": "shipping_delivery",
        "name": "Shipping & Delivery",
        "description": "Shipping methods, delivery times, tracking",
        "icon": "truck",
        "keywords": ["shipping", "delivery"],
        "sampleQuestions": ["When will it arrive?", "Track my order"],
        "enabled": true
    }
]

POST /public/topics/contextual

Get topics filtered by page context.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/public/topics/contextual" \
  -H "Content-Type: application/json" \
  -d '{
    "page_type": "product",
    "product_id": 123,
    "category_id": 45,
    "utm_source": "email",
    "utm_campaign": "summer_sale"
  }'

Response:

{
    "topics": [
        {
            "id": "product_information",
            "name": "Product Information",
            "relevance_score": 85
        },
        {
            "id": "size_fit",
            "name": "Size & Fit",
            "relevance_score": 80
        }
    ],
    "context": {
        "page_type": "product",
        "product_id": 123
    }
}

6. RAG Endpoints

RAG (Retrieval-Augmented Generation) endpoints manage product indexing for semantic search.

GET /rag/status

Get current indexing status.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/rag/status" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "isIndexing": false,
    "totalProducts": 1250,
    "indexedProducts": 1200,
    "vectorCount": 1200,
    "lastIndexedAt": "2024-01-15T14:30:00Z",
    "status": "completed",
    "storageBackend": "supabase"
}

POST /rag/index

Start or stop product indexing.

# Start indexing
curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "action": "start" }'

# Stop indexing
curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "action": "stop" }'

DELETE /rag/index

Clear all indexed products.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/rag/index" \
  -H "X-WP-Nonce: your_nonce_here"

POST /rag/index/product/{id}

Index a single product (useful for testing).

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index/product/123" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "success": true,
    "message": "Product \"Premium Widget\" indexed successfully.",
    "product": {
        "id": 123,
        "name": "Premium Widget"
    }
}

POST /rag/test-connection

Test Supabase vector database connection.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/test-connection" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "supabaseUrl": "https://your-project.supabase.co",
    "supabaseApiKey": "your-api-key",
    "supabaseTableName": "product_embeddings"
  }'

Response (200 OK):

{
    "success": true,
    "message": "Connected successfully! Found 1200 embeddings.",
    "stats": {
        "total_embeddings": 1200,
        "newest_embedding": "2024-01-15T14:30:00Z"
    }
}

Excluded Products Management

GET /rag/excluded-products

Get list of products excluded from indexing.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

[123, 456, 789]

POST /rag/excluded-products

Add products to exclusion list.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "product_ids": [123, 456] }'

DELETE /rag/excluded-products/{id}

Remove a product from exclusion list.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products/123" \
  -H "X-WP-Nonce: your_nonce_here"

7. License Endpoints

License management endpoints require manage_options capability.

GET /license

Get current license status.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/license" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "is_valid": true,
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "plan": "professional",
    "expires_at": "2025-01-15T00:00:00Z",
    "features": {
        "max_sessions": 10000,
        "ai_provider": "openai",
        "vector_search": true
    }
}

POST /license/activate

Activate a license key.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/activate" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{ "license_key": "XXXX-XXXX-XXXX-XXXX" }'

Response (200 OK):

{
    "success": true,
    "message": "License activated successfully.",
    "data": { ... }
}

Error Response (400):

{
    "code": "invalid_license",
    "message": "The license key is invalid or has expired.",
    "data": { "status": 400 }
}

POST /license/deactivate

Deactivate the current license.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/deactivate" \
  -H "X-WP-Nonce: your_nonce_here"

POST /license/validate

Force revalidation of the current license.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/validate" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "success": true,
    "is_valid": true,
    "data": { ... }
}

8. Promotions Endpoints

Manage product promotions for boosted visibility in chat responses.

GET /promotions

List all promotions.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/promotions?active=true" \
  -H "X-WP-Nonce: your_nonce_here"

POST /promotions

Create a new promotion.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/promotions" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: your_nonce_here" \
  -d '{
    "name": "Summer Sale",
    "type": "manual",
    "product_ids": [123, 456, 789],
    "boost_multiplier": 2.0,
    "active": true,
    "valid_from": "2024-06-01T00:00:00Z",
    "valid_to": "2024-08-31T23:59:59Z"
  }'

GET /promotions/products

Get all promoted product IDs (used by RAG system).

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/promotions/products" \
  -H "X-WP-Nonce: your_nonce_here"

Response:

{
    "product_ids": [123, 456, 789, 1011],
    "count": 4
}

Utility Endpoints

GET /products/search

Search WooCommerce products.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/products/search?search=hiking&category=outdoor&per_page=20" \
  -H "X-WP-Nonce: your_nonce_here"

GET /categories

Get all product categories.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/categories" \
  -H "X-WP-Nonce: your_nonce_here"

GET /tags

Get all product tags.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/tags" \
  -H "X-WP-Nonce: your_nonce_here"

9. Error Handling

Error Response Format

All error responses follow the WordPress REST API standard format:

{
    "code": "error_code",
    "message": "Human-readable error message",
    "data": {
        "status": 400
    }
}

Common Error Codes

Handling Errors in JavaScript

async function sendMessage(sessionId, message) {
    try {
        const response = await fetch('/wp-json/woo-ai/v1/chat/message', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-WP-Nonce': wooAiChatbot.nonce
            },
            body: JSON.stringify({ session_id: sessionId, message })
        });

        if (!response.ok) {
            const error = await response.json();

            switch (error.code) {
                case 'rate_limit_exceeded':
                    // Show rate limit message, retry after delay
                    await delay(5000);
                    return sendMessage(sessionId, message);

                case 'invalid_session':
                    // Create new session and retry
                    const newSession = await createSession();
                    return sendMessage(newSession.session_id, message);

                default:
                    throw new Error(error.message);
            }
        }

        return await response.json();
    } catch (err) {
        console.error('Chat API error:', err);
        throw err;
    }
}

10. Versioning and Deprecation

API Version History

Deprecation Policy

• Deprecated endpoints continue to function for at least 2 major versions
• Deprecation warnings are logged in WP_DEBUG mode
• Migration guides are provided in release notes

Recommended Migration

Replace legacy namespace in your integrations:

// Before (deprecated)
fetch('/wp-json/woo-ai-chatbot/v1/chat/message', { ... });

// After (current)
fetch('/wp-json/woo-ai/v1/chat/message', { ... });

Appendix: Quick Reference

Chat Endpoints Summary

Analytics Endpoints Summary

Admin Resource Endpoints Summary