Hooks reference
Every action and filter in Siteryn AI Support Agent and Pro, with exact signatures, checked against the code. Free hooks start with siteryn_ai_support_agent_.
Lifecycle
| Hook | Type | Arguments · when |
|---|---|---|
siteryn_ai_support_agent_loaded | action | ( Plugin $plugin ). Free has booted. Extensions start here. |
siteryn_ai_support_agent_upgrade | action | ( string|false $old_version, string $new_version ). init (20) on a version change. |
siteryn_ai_support_agent_deactivate | action | (). On deactivation. |
Chat pipeline
| Hook | Type | Arguments · purpose |
|---|---|---|
…_chat_request | action | ( WP_REST_Request $request ). Start of /chat. |
…_take_over_message | filter | ( bool $take_over, string $message, Conversation $conversation ). Send straight to a person. $message isn't redacted yet. |
…_hand_off | filter | ( ?array $handoff, int $conversation_id ). Return ['status', 'reply']. |
…_max_concurrent_requests | filter | ( int $limit = 20 ). Site-wide in-flight cap; 0 = none. |
…_redact_message | filter | ( string $text, bool $contact ). Extra redaction. |
…_chat_context | filter | ( array $context, string $message, Conversation $conversation ). Add facts, knowledge or products. |
…_store_facts | filter | ( array $facts, string[] $sources ). id => [label, text]. |
…_knowledge_documents | filter | ( array $documents, string[] $sources ). Add searchable knowledge. |
…_policy_page_ids | filter | ( array $ids ). Policy pages used. |
…_rank_documents | filter | ( array $ranked, string $query, array $documents, int $limit ). Replace the ranking. |
…_stop_words | filter | ( string[] $words ) |
…_prompt | filter | ( array{system,prompt} $parts, array $context, array $settings ) |
…_system_rules | filter | ( array $rules, array $context ). json_shape stays last. |
…_parsed_answer | filter | ( array $answer, int[] $offered, string $message, Conversation $conversation ). AI answers only. |
…_reply_cards | filter | ( int[] $ids, string[] $cited, array $context ). Posts shown as content cards. |
…_chat_result | filter | ( array $result, string $message, Conversation $conversation, array $context ) |
…_chat_answered | action | ( array $result, string $message, Conversation $conversation, array $context, ?CompletionResponse $response ). Before saving; $response is null for basic answers. |
…_chat_failed | action | ( string $code, WP_Error $cause ). Provider errors. |
…_guest_fingerprint | filter | ( string $fingerprint ). Real client IP behind a proxy. |
…_chat_response | filter | ( array $data, array $result, WP_REST_Request $request ). /chat and /contact; add extra HTML or new keys. |
…_content_cards | filter | ( string $html, int[] $ids ) |
…_allowed_origins | filter | ( string[] $hosts ). Allow another origin, e.g. headless. |
…_basic_fallback | filter | ( ?array $answer, string $stage, string $message, string[] $words, array $context ). $stage: no_terms|no_match. |
…_basic_synonyms | filter | ( array $map ). Synonyms, other languages. |
…_basic_products_intro | filter | ( string $intro, array $query ) |
…_handoff_phrases | filter | ( string[] $phrases ). Phrases that offer contact. |
…_handoff_explicit_phrases | filter | ( string[] $phrases ). Phrases that go straight to a person. |
Contact form
| Hook | Type | Arguments |
|---|---|---|
…_contact_site_hourly_limit | filter | ( int $limit = 50 ) |
…_contact_store | filter | ( ?Conversation $kept, array $fields, ?Conversation $conversation, int $user_id ) |
…_contact_email | filter | ( array $email, array $fields, ?Conversation $conversation ). to, subject, message, headers. |
…_contact_request | action | ( array $fields, ?Conversation $conversation ). After the email is sent. |
Conversations
| Hook | Type | Arguments |
|---|---|---|
…_conversation_created | action | ( array $conversation ) |
…_conversation_status | action | ( int $conversation_id, string $new_status, string $old_status ) |
…_conversation_deleted | action | ( int $conversation_id ) |
…_message_added | action | ( array $message, array $conversation ) |
…_retention_days | filter | ( int $days ) |
…_conversations_purged | action | ( int $expiry, int $deleted ) |
…_conversation_state | filter | ( array $state, array $row ) |
…_message_view | filter | ( array $view, array $message ) |
…_agent_name | filter | ( string $name, int $user_id ) |
…_chat_feature | filter | ( bool $enabled = false, string $feature ). Free asks for live_chat; extensions add their own features (Pro: attachments). |
Live chat & Inbox
| Hook | Type | Arguments |
|---|---|---|
…_is_agent | filter | ( bool $can, int $user_id ) |
…_agents_available | filter | ( bool $available, int[] $online ) |
…_agent_capabilities | filter | ( string[] $capabilities ) |
…_handoff_requested | action | ( int $conversation_id, bool $online ) |
…_conversation_accepted | action | ( int $conversation_id, int $agent_id, int $previous_agent_id ) |
…_conversation_released | action | ( int $conversation_id ). Resolve or back to the assistant. |
…_handoff_email | filter | ( array $email, array $conversation ) |
…_inbox_url | filter | ( string $url, int $conversation_id ) |
…_inbox_menu_slug · …_is_inbox_screen | filter | ( string $slug ) · ( bool $is_screen ) |
…_inbox_filters | filter | ( array $definitions ) |
…_inbox_query | filter | ( array $query, string $filter, array $args ) |
…_inbox_summary · …_inbox_conversation | filter | ( array $data, array $row ) |
…_inbox_message | filter | ( array $view, array $message, int $conversation_id ) |
…_inbox_context | filter | ( array $items, array $row ) |
…_inbox_notes | filter | ( bool $enabled = false ) |
…_inbox_action | filter | ( true|WP_Error|null $result, string $action, array $row, int $agent, array $args ). Runs under the conversation lock. |
…_inbox_polled | action | ( int $agent ) |
…_inbox_poll | filter | ( array $data, int $agent ) |
…_inbox_toolbar · _before_layout · _actions · _composer | action | (). Add Inbox UI. |
Knowledge, shop & catalog
| Hook | Type | Arguments |
|---|---|---|
…_kb_show_in_menu | filter | ( bool|string $show_in_menu = false ) |
…_shop_active | filter | ( bool $active ) |
…_capability | filter | ( string $capability ) |
…_is_shoppable | filter | ( bool $shoppable, WC_Product $product ) |
…_search_results | filter | ( int[] $ids, SearchQuery $query, int $limit ) |
…_search_stopwords · …_support_words | filter | ( string[] $words ) |
…_candidates | filter | ( int[] $ids, SearchQuery $query, string $message, Conversation $conversation ) |
…_shop_product_context | filter | ( array $context, WC_Product $product, string[] $allowed_fields ) |
…_shop_query | filter | ( ?SearchQuery $query, string $message, Conversation $conversation ) |
…_product_card | filter | ( array $card, WC_Product $product ) |
…_product_card_after | action | ( WC_Product $product, array $card ). Inside product-card.php. |
…_product_card_options | filter | ( array $options ). fields, layout, button_text, new_tab. |
AI providers
| Hook | Type | Arguments |
|---|---|---|
…_providers | filter | ( array $providers ). Key must equal get_id(). |
…_provider_config | filter | ( ProviderConfig $config ) |
…_max_retries | filter | ( int $retries = 1, string $provider_id ). 0–2; only on 429 and 5xx. |
…_allow_insecure_local_endpoint | filter | ( bool $allow = false, string $url ). localhost only. |
Storefront & templates
| Hook | Type | Arguments |
|---|---|---|
…_show_chat | filter | ( bool $show, string $display_on ). Floating chat only, not the shortcode. |
…_chat_config | filter | ( array $config, array $settings ). window.siterynAisupChat. |
…_chat_chips | filter | ( array $chips, array $settings ). [{label, message}]. |
…_chat_chips_label | filter | ( string $label = 'Browse', array $settings ) |
…_chat_avatar | filter | ( array $avatar, array $settings ) |
…_show_branding | filter | ( bool $show, array $settings ) |
…_template_path | filter | ( string $path, string $name ) |
…_before_template · …_after_template | action | ( string $name, array $args ) |
…_chat_composer_tools | action | ( array $args ). Inside the chat's message bar, before the text field (chat-widget.php). |
Admin & settings
| Hook | Type | Arguments |
|---|---|---|
…_settings_sections · …_settings_fields | filter | ( array $items ) |
…_settings_get_all | filter | ( array $settings ). Runtime only, never saved. |
…_settings_reset_actions | filter | ( array $actions ) |
…_settings_save_redirect | filter | ( false|array $redirect, string $option_name ) |
…_settings_nav_visible | filter | ( bool $visible, string $section ) |
…_settings_nav_icon · _nav_sublabel · _nav_badge · _settings_description | filter | ( string $value, string $section ) |
…_settings_tab_before · _tab_after · _main_after · _sidebar | action | ( string $section ). _main_after and _sidebar fire on the Chat Widget tab only. |
…_before_merged_sections | action | ( string $tab ). Before the sections an extension merged into a Free tab. |
…_status_cards | filter | ( array $cards ). System Status summary cards (label, value, icon, variant); runs only while an extension (Pro) is active. |
…_render_field_{$type} | action | ( array $field, mixed $value, string $name, string $id ) |
…_sanitize_field_{$type} | filter | ( mixed $default, mixed $raw, array $field ) |
…_knowledge_tools | action | ( string $place ). Add Knowledge Base tools: header (next to the buttons) or panel (below the list). |
…_kb_action | filter | ( array|WP_Error|null $result, string $do ) |
…_kb_entry | filter | ( array $entry, WP_Post $post ) |
…_kb_starter_entries | filter | ( array $entries ) |
…_privacy_paragraphs | filter | ( array $paragraphs ) |
siteryn_dashboard_plugins | filter | ( array $plugins ). Shared by every Siteryn plugin: the cards on Siteryn → Welcome (slug, title, icon). |
siteryn_deactivation_feedback_endpoint | filter | ( string $url ). Shared: where the optional deactivation survey is sent. |
Pro hooks Pro
Prefix siteryn_ai_support_agent_pro_.
| Hook | Type | Arguments · purpose |
|---|---|---|
…pro_loaded | action | ( Plugin $plugin ). Pro booted. |
…pro_features_loaded | action | ( Plugin $plugin ). Premium features loaded (license active). |
…pro_upgrade | action | ( string|false $old, string $new ) |
…pro_activated · …pro_deactivate | action | () |
…pro_license_activated | action | ( ActivationOutcome $outcome ). After every attempt, including failures. |
…pro_license_deactivated | action | ( bool $done ) |
…pro_order_document | filter | ( array $document, WC_Order $order ) |
…pro_order_guidance | filter | ( string[] $lines, WC_Order $order ) |
…pro_find_order | filter | ( ?WC_Order $order, string $number, int $customer_id ). Custom order numbers. |
…pro_guest_order_verified | action | ( int $conversation_id, int $order_id ) |
…pro_reply_email | filter | ( array $email, array $message, array $conversation ) |
…pro_digest_text | filter | ( string $text, array $summary ) |
…pro_stock_alert_added | action | ( int $product_id, string $email ) |
…pro_stock_alert_email | filter | ( array $email, WC_Product $product ) |
…pro_attachment_added | action | ( array $message ) |
…pro_conversation_transferred | action | ( int $conversation_id, int $to_agent_id, int $from_agent_id ) |
…pro_conversation_routed | action | ( int $conversation_id, int $agent_id ) |
…pro_kb_learned | action | ( array $entries, int $conversation_id ) |
…pro_list_phrases | filter | ( array $lists ). sale, new, best, rating. |
…pro_content_query | filter | ( array $args, string $message ) |
…pro_content_list_phrases | filter | ( array $lists ). latest, popular. |
…pro_content_card | filter | ( array $card, WP_Post $post ) |
…pro_lead_captured | action | ( int $conversation_id, string $name, string $email ) |
…pro_webhook_payload | filter | ( array $payload, string $event, int $conversation_id ) |
…pro_webhook_capability | filter | ( string $capability = 'manage_options' ) |
…pro_is_admin_screen | filter | ( bool $is_pro_screen, string $hook_suffix ) |
…pro_admin_config | filter | ( array $config ) |
…pro_template_path | filter | ( string $path, string $name ) |
…pro_builder_html | filter | ( string $html, string $context ). block|elementor|bricks. |