Athenian AI Voice Assistant

Developer starting point

This baseline describes the reviewed voice-assistant implementation. It does not claim microphone capture, speech synthesis, or an external provider transaction has succeeded.

Admin Workflow

Settings Location

The plugin adds an admin settings page at:

Settings → AI Voice Assistant

The page is registered with the manage_options capability and uses the WordPress Settings API.

Admin Settings

| Setting | Option Field | Purpose | |---|---|---| | OpenAI API Key | openai_api_key | Stores the fallback OpenAI key used when AWC_AI_Core is not available. | | OpenAI Model | openai_model | Stores the fallback model identifier. Defaults to gpt-4.1-mini. | | System Prompt | system_prompt | Controls the assistant persona, behavior, tone, and tool-use instructions. | | Inbound Shared Secret | shared_secret | Optional token required for inbound REST calls. |

Operational Setup Flow

1. Install and activate the plugin.
2. Open Settings → AI Voice Assistant.
3. Add an OpenAI API key, unless the site already provides AWC_AI_Core.
4. Confirm or revise the OpenAI model.
5. Add a concise system prompt describing the voice assistant’s role.
6. Configure a shared secret for inbound webhook protection.
7. Configure Twilio or another telephony layer to send transcribed utterances to /wp-json/aava/v1/ai-route.
8. Test with a known phone number associated with WooCommerce billing data.

---

REST API Workflow

Endpoint

POST /wp-json/aava/v1/ai-route

Authentication / Permission Model

If no shared secret is configured, the endpoint accepts requests without token validation. If a shared secret is configured, inbound requests must include one of the following:

X-AAVA-Token: your-secret-token

or:

/wp-json/aava/v1/ai-route?token=your-secret-token

Expected JSON Payload

{
  "from": "+16065551234",
  "utterance": "Where is my order?",
  "session_id": "optional-session-id"
}

Successful Response Shape

{
  "error": false,
  "from": "+16065551234",
  "session_id": "optional-session-id",
  "utterance": "Where is my order?",
  "reply_text": "Your most recent order is currently processing...",
  "tool_results": [],
  "caller_context": {
    "raw_from": "+16065551234",
    "normalized_phone": "6065551234",
    "user_id": 123,
    "user_email": "[email protected]",
    "recent_orders": []
  }
}

Error Cases

| Condition | Response | |---|---| | Missing utterance | HTTP 400, error: true, message Missing utterance. | | Invalid shared secret | HTTP 403, WordPress REST error aava_forbidden | | Missing OpenAI API key | HTTP 500, OpenAI client error OpenAI API key is not configured. | | OpenAI HTTP error | HTTP 500, returned OpenAI error message | | Empty OpenAI response | HTTP 500, OpenAI returned no message. |

---

Tracking Metadata Handling

When formatting orders for AI context, the plugin checks these default tracking metadata keys:

_tracking_number
_wc_shipment_tracking_items
tracking_number

Developers can customize the list with:

add_filter( 'aava_tracking_meta_keys', function( $keys ) {
    $keys[] = '_custom_tracking_meta_key';
    return $keys;
} );

This makes the plugin adaptable to different shipment, fulfillment, and tracking plugins without hard-coding one provider.

---

Technical Architecture

Main Files

| File | Purpose | |---|---| | athenian-ai-voice-assistant.php | Plugin header, constants, autoloader, bootstrap hook. | | includes/class-aava-plugin.php | Core singleton, initializes admin, OpenAI client, router, and media manager. | | includes/class-aava-admin.php | Admin settings page and Settings API fields. | | includes/class-aava-router.php | REST route registration, shared-secret validation, AI routing flow. | | includes/class-aava-openai-client.php | OpenAI client wrapper with AWC AI Core reuse and direct HTTP fallback. | | includes/class-aava-toolbox.php | OpenAI tool schema and local tool execution. | | includes/class-aava-media-manager.php | STT/TTS provider registry and placeholder provider behavior. | | assets/admin.css | Small admin settings-page styling. | | docs/athenian-platform-marketing.md | Platform marketing placement notes. | | docs/athenian-platform-technical.md | Platform technical brief and taxonomy placement notes. |

Bootstrap Pattern

The plugin defines constants, registers a simple class autoloader for AAVA_* classes, and starts the main singleton on plugins_loaded:

add_action( 'plugins_loaded', 'aava_bootstrap' );

Core Class Responsibilities

| Class | Responsibility | |---|---| | AAVA_Plugin | Main singleton and service initializer. | | AAVA_Admin | Admin UI, option registration, sanitization, and settings fields. | | AAVA_Router | REST endpoint registration, token validation, AI route handling. | | AAVA_OpenAI_Client | OpenAI API access and compatibility with AWC_AI_Core. | | AAVA_Toolbox | Tool schema definition, tool execution, caller/order context formatting. | | AAVA_Media_Manager | Provider registration for future speech-to-text and text-to-speech flows. |

---

WordPress Hooks and Integration Points

| Hook / API | Usage | |---|---| | plugins_loaded | Boots the plugin singleton. | | admin_menu | Adds the AI Voice Assistant settings page. | | admin_init | Registers plugin settings and fields. | | admin_enqueue_scripts | Loads admin CSS only on the plugin settings page. | | rest_api_init | Registers the AI route REST endpoint. | | register_rest_route() | Creates aava/v1/ai-route. | | wc_get_orders() | Looks up WooCommerce orders by billing phone. | | WP_Query | Searches posts, pages, and products. | | apply_filters( 'aava_caller_context', ... ) | Allows caller context enrichment. | | apply_filters( 'aava_tracking_meta_keys', ... ) | Allows shipment tracking metadata customization. |

---

Data Model and Stored Configuration

The plugin stores configuration in a single WordPress option:

aava_settings

Option shape:

array(
    'openai_api_key' => '',
    'openai_model'   => 'gpt-4.1-mini',
    'system_prompt'  => '',
    'shared_secret'  => '',
)

The plugin does not currently register custom database tables, custom post types, custom taxonomies, or scheduled events.

---

WooCommerce Integration

The plugin integrates with WooCommerce in a focused way:

• Detects WooCommerce availability by checking wc_get_orders().
• Searches recent orders by _billing_phone with a LIKE meta query.
• Resolves a user account from the matched order user ID, if available.
• Formats order details into compact AI-readable context.
• Includes order status, order number, totals, item names/quantities, and tracking metadata.
• Uses WooCommerce APIs rather than direct order-table SQL.

This makes the plugin useful for phone-based support questions such as:

• “Where is my order?”
• “What did I order last time?”
• “Has my order shipped?”
• “Do you have information about my recent purchase?”

---

OpenAI Integration

Shared Athenian AI Core Path

If AWC_AI_Core exists, the plugin attempts to use:

AWC_AI_Core::get_api_key();
AWC_AI_Core::get_default_model();
AWC_AI_Core::openai_chat( $body );

This allows sites already running Athenian AI Chat for WooCommerce to centralize OpenAI configuration and HTTP behavior.

Standalone Path

If AWC_AI_Core is not available, the plugin uses:

POST https://api.openai.com/v1/chat/completions

with:

• bearer token from aava_settings['openai_api_key'],
• model from aava_settings['openai_model'],
• JSON body generated from the route handler,
• 20-second WordPress HTTP timeout.

---

Media Manager / Voice Provider Scaffolding

The AAVA_Media_Manager class provides a registry for speech-to-text and text-to-speech providers:

AAVA_Media_Manager::register_stt_provider( $key, $callback );
AAVA_Media_Manager::register_tts_provider( $key, $callback );

The current default provider keys are registered as twilio, but both default callbacks are no-op placeholders.

Current placeholder behavior:

• STT returns a note indicating that speech-to-text is not implemented yet.
• TTS returns a note indicating that text-to-speech is not implemented yet.

This is an important implementation boundary: the current plugin expects inbound text/transcription, not raw audio.

---

Security and Privacy Notes

Current Safeguards

• Admin settings require manage_options.
• REST endpoint can require a shared secret.
• Shared secret can be sent through X-AAVA-Token or ?token=.
• Inbound from, utterance, and session_id values are sanitized with sanitize_text_field().
• System prompt is sanitized with wp_kses_post().
• API key and secret fields are sanitized with sanitize_text_field().
• OpenAI HTTP errors are converted into WordPress errors instead of being treated as successful replies.

Implementation Considerations

The current version stores the OpenAI API key in the WordPress options table. For higher-security deployments, a future version should integrate with Athenian Secure API Key Manager, environment constants, encrypted storage, or a secrets service.

The current route uses a shared-secret model. For production Twilio deployments, additional validation should be considered, such as Twilio signature verification, rate limiting, IP allowlisting where practical, structured logging, replay protection, and audit trails.

Sensitive Data Considerations

Because the plugin sends caller context and order metadata to OpenAI, production deployments should confirm:

• what order data is included in prompts,
• whether phone numbers or emails should be masked,
• whether data retention settings are appropriate,
• whether a consent notice is needed for phone AI support,
• whether staff-only/internal mode should differ from customer-facing mode.

---