Action reference

Every action Aimogen Pro fires, with its parameters and when it fires, plus practical logging and monitoring examples.

Actions notify your code that something happened. They cannot change behaviour — for that use filters.

Practical uses#

Log every failure to your monitoring system:

php

add_action( 'aiomatic_on_error', function ( $error, $prompt, $model, $assistant_id ) {
    error_log( sprintf( '[Aimogen] %s failed on %s: %s', $assistant_id ?: 'model', $model, $error ) );
}, 10, 4 );

Alert when an API key is quarantined:

php

add_action( 'aimogen_smart_key_state_changed', function ( $fingerprint, $state ) {
    if ( $state['status'] !== 'quarantined' ) {
        return;
    }
    wp_mail(
        get_option( 'admin_email' ),
        'Aimogen: an API key was quarantined',
        sprintf(
            "Provider: %s\nReason: %s\nUntil: %s",
            $state['provider'],
            $state['category'],
            gmdate( 'Y-m-d H:i', $state['cooldown_until'] )
        )
    );
}, 10, 2 );

The fingerprint is an HMAC of the key, never the key itself. See Smart API-key rotation.

Record failovers:

php

add_action( 'aimogen_reliability_failover', function ( $from, $to, $category, $error ) {
    error_log( sprintf( '[Aimogen] failover %s -> %s (%s)', $from, $to, $category ) );
}, 10, 4 );

Audit every tool call an agent or chatbot makes:

php

add_action( 'aiomatic_tool_result', function ( $output ) {
    error_log( '[Aimogen tool] ' . wp_json_encode( $output ) );
} );

Worth doing on any site with extensions or agents enabled. See Agent security.

Warn when token budgets are tight:

php

add_action( 'aiomatic_on_token_limit_warning', function ( $available, $prompt, $model ) {
    error_log( sprintf( '[Aimogen] only %d tokens left for %s', $available, $model ) );
}, 10, 3 );

Complete reference#

Action	Parameters	Fires when
`aimogen_api_ready`	`$GLOBALS['aimogen_api']`	The PHP API object is available. Use this if your code loads early.
`aimogen_reliability_failover`	`$current_model, $candidate, $category, $error, $context`	Reliability Mode switched models after a failure.
`aimogen_smart_key_recovered`	`$context['current_key_id'], isset($context['current_key_pro...`	An API key returned to healthy rotation.
`aimogen_smart_key_state_changed`	`$fingerprint, $state`	An API key entered or left cooldown or quarantine. The fingerprint is an HMAC, never the key.
`aiomatic_after_assistant_ai_query`	`$response_ai, $token, $assistant_id, $local_assistant_id, $role, $user_question, $thread_id, $no_internet, $no_embeddings, $env, $retry_count, $embedding_namespace, $stream, $function_result, $vision_file, $file_data`	Immediately after an Assistants API request.
`aiomatic_after_chat_ai_query`	`$response_text, $token, $model, $chatgpt_obj, $available_tokens, $temperature, $top_p, $presence_penalty, $frequency_penalty, $is_chat, $env, $retry_count, $finish_reason, $error, $no_internet, $no_embeddings, $functi...`	Immediately after a chat completion request.
`aiomatic_ai_form_image_reply`	`$tmpimg`	An AI Form produced an image.
`aiomatic_ai_image_reply`	`$tmpimg`	An AI image was produced.
`aiomatic_aicontent_reply`	`$new_post_content`	An [aicontent] shortcode produced content.
`aiomatic_assistant_image_reply`	`$image`	An assistant produced an image.
`aiomatic_assistant_text_reply`	`$new_post_content`	An assistant produced text.
`aiomatic_audio_converter_reply`	`$aiomatic_result`	An audio transcription completed.
`aiomatic_before_assistant_ai_query`	`$token, $assistant_id, $local_assistant_id, $role, $user_question, $thread_id, $no_internet, $no_embeddings, $env, $retry_count, $embedding_namespace, $stream, $function_result, $vision_file, $file_data, $rcid, $rcsig`	Immediately before an Assistants API request.
`aiomatic_before_chat_ai_query`	`$token, $model, $chatgpt_obj, $available_tokens, $temperature, $top_p, $presence_penalty, $frequency_penalty, $is_chat, $env, $retry_count, $finish_reason, $error, $no_internet, $no_embeddings, $functions, $stream, $v...`	Immediately before a chat completion request.
`aiomatic_before_completion_ai_query`	`$token, $model, $aicontent, $available_tokens, $temperature, $top_p, $presence_penalty, $frequency_penalty, $is_chat, $env, $retry_count, $finish_reason, $error, $no_internet, $no_embeddings, $stream, $user_question, ...`	Immediately before a completion request.
`aiomatic_before_vision_file_process`	`$vision_file, $aicontent, $model, $assistant_id`	Before an uploaded vision file is processed.
`aiomatic_calling_chatbot`	`$input_text, $model`	A chatbot request is starting.
`aiomatic_calling_forms`	`$input_text, $model`	An AI Form request is starting.
`aiomatic_calling_stream`	`$input_text, $model`	A streaming request is starting.
`aiomatic_chat_reply`	`$aiomatic_result`	A chatbot reply was produced.
`aiomatic_cloudflare_image_reply`	`$temp_get_imgs`	A Cloudflare Workers image was produced.
`aiomatic_comment_reply`	`$new_post_content`	An AI comment reply was produced.
`aiomatic_editor_reply`	`$response_text`	The AI Content Editor produced a result.
`aiomatic_form_reply`	`$return_me`	An AI Form produced a result.
`aiomatic_google_image_reply`	`$temp_get_imgs`	A Google image was produced.
`aiomatic_ideogram_image_reply`	`$temp_get_imgs`	An Ideogram image was produced.
`aiomatic_image_chat_reply`	`$aiomatic_result`	A chatbot image reply was produced.
`aiomatic_midjourney_image_reply`	`$temp_get_imgs`	A Midjourney image was produced.
`aiomatic_on_error`	`$error, $aicontent, $model, $assistant_id`	A request failed. The error text is the provider message.
`aiomatic_on_streamed_query`	`$aicontent, $model, $assistant_id`	A streamed request started.
`aiomatic_on_successful_response`	`$response_text, $aicontent, $model, $assistant_id`	A request succeeded.
`aiomatic_on_token_limit_warning`	`$available_tokens, $aicontent, $model, $assistant_id`	The token budget is close to the limit.
`aiomatic_replicate_image_reply`	`$temp_get_imgs`	A Replicate image was produced.
`aiomatic_stable_image_reply`	`$temp_get_imgs`	A Stability.AI image was produced.
`aiomatic_tax_description_reply`	`$new_post_content`	A taxonomy description was produced.
`aiomatic_text_moderation_reply`	`$aiomatic_result`	A moderation check completed.
`aiomatic_text_writer_reply`	`$new_post_content`	The AI writer produced content.
`aiomatic_tool_direct_message`	`$add_me`	A tool produced a direct message for the conversation.
`aiomatic_tool_result`	`$add_me`	A tool call returned a result.

Notes#

The before and after query actions carry very long parameter lists. They expose the full request context. Request only the parameters you need; add_action() with a low $accepted_args is fine.

The *_reply actions fire after a specific feature produced output. They are the convenient place to post-process or record per-feature results.

aimogen_api_ready is the correct place to use the PHP API from code that loads early.

Still stuck? Open a support ticket and include the diagnostics from Aimogen Pro › System & Logs › System Info.

Action reference

Practical uses#

Complete reference#

Notes#

Related#