Chat hooks

This page lists the 16 hooks of this group. Each entry shows its type, the version it arrived in, where it runs, its arguments and a starting point.

• addochat_active_minutes
• addochat_backend_reply
• addochat_backend_request
• addochat_backends
• addochat_challenge_passed
• addochat_conversation_updated
• addochat_handoff
• addochat_handoff_email
• addochat_limit_reached
• addochat_message_received
• addochat_message_stored
• addochat_providers
• addochat_reply_sent
• addochat_rule_matched
• addochat_system_prompt
• addochat_visitor_ip

addochat_active_minutes

FilterSince 0.1.0 Runs in src/Data/Conversations.php.

Filters how many minutes after its last message a conversation counts as active (tab Live now).

Argument	Type	Description
$minutes	int	Minutes. Default 15.

add_filter( 'addochat_active_minutes', function ( $minutes ) {
	return $minutes;
} );

addochat_backend_reply

FilterSince 0.1.0 Runs in src/Chat/Endpoint.php.

Filters the answer of the backend before it is stored and shown.

Argument	Type	Description
$reply	\Addochat\Agent\Reply	The answer (or failure).
$request	\Addochat\Agent\Request	What the backend got.

add_filter( 'addochat_backend_reply', function ( $reply, $request ) {
	return $reply;
}, 10, 2 );

addochat_backend_request

FilterSince 0.1.0 Runs in src/Chat/Endpoint.php.

Filters what the backend gets, before it is sent. For a webhook this is the JSON body (contract 1).

Argument	Type	Description
$payload	array<string, mixed>	Request fields (see docs/webhook.md).
$conversation	array<string, mixed>	Conversation row.

add_filter( 'addochat_backend_request', function ( $payload, $conversation ) {
	return $payload;
}, 10, 2 );

addochat_backends

FilterSince 0.1.0 Runs in src/Agent/Backends.php.

Filters the agent backends by id. Add your own class that implements \Addochat\Agent\Backend, and add its id to the options of the backend setting with addochat_settings_fields.

Argument	Type	Description
$backends	array<string, \Addochat\Agent\Backend>	Backends by id.

add_filter( 'addochat_backends', function ( $backends ) {
	return $backends;
} );

addochat_challenge_passed

FilterSince 0.1.0 Runs in src/Chat/Endpoint.php.

Filters whether the visitor passed a check (for example Cloudflare Turnstile) after sending too many messages in an hour. Return true when $challenge is valid; the visitor counter then starts again.

Argument	Type	Description
$passed	bool	Whether the check passed. Default false.
$challenge	string	Check token the widget sent.
$request	\WP_REST_Request	The request.

add_filter( 'addochat_challenge_passed', function ( $passed, $challenge, $request ) {
	return $passed;
}, 10, 3 );

addochat_conversation_updated

ActionSince 0.1.0 Runs in src/Data/Conversations.php.

Fires after a conversation changed (mode, status, owner, contact details). The network uses it to tell the central site.

Argument	Type	Description
$id	int	Conversation id.
$fields	array<string, mixed>	Changed columns.

add_action( 'addochat_conversation_updated', function ( $id, $fields ) {
	// ...
}, 10, 2 );

addochat_handoff

ActionSince 0.1.0 Runs in src/Chat/Handoff.php.

Fires once per conversation when a visitor leaves an email address for a colleague. Use it to make a ticket in your own system.

Argument	Type	Description
$conversation	array<string, mixed>	Conversation row (contact_email, contact_name, page_url, uuid).
$reason	string	Why: "contact" (left an email address).

add_action( 'addochat_handoff', function ( $conversation, $reason ) {
	// ...
}, 10, 2 );

addochat_handoff_email

FilterSince 0.1.0 Runs in src/Chat/Handoff.php.

Filters the email to the team when a visitor leaves an email address. Return an empty to to send none.

Argument	Type	Description
$mail	array{to: string[], subject: string, body: string, headers: string[]}	Email.
$conversation	array<string, mixed>	Conversation row.

add_filter( 'addochat_handoff_email', function ( $mail, $conversation ) {
	return $mail;
}, 10, 2 );

addochat_limit_reached

ActionSince 0.1.0 Runs in src/Chat/Endpoint.php.

Fires when a visitor or the site reaches a limit.

Argument	Type	Description
$state	string	offer_human (per conversation), challenge (per visitor per hour) or closed (AI answers per day).

add_action( 'addochat_limit_reached', function ( $state ) {
	// ...
} );

addochat_message_received

ActionSince 0.1.0 Runs in src/Chat/Endpoint.php.

Fires after a visitor message was stored.

Argument	Type	Description
$conversation	array<string, mixed>	Conversation row.
$message_id	int	Message id.
$message	string	Message text.

add_action( 'addochat_message_received', function ( $conversation, $message_id, $message ) {
	// ...
}, 10, 3 );

addochat_message_stored

ActionSince 0.1.0 Runs in src/Data/Messages.php.

Fires after a message was stored. The network uses it to send messages on to the central site.

Argument	Type	Description
$conversation_id	int	Conversation id.
$message_id	int	Message id.
$role	string	Role.
$payload	array<string, mixed>	Extra data (origin when it came from another site).

add_action( 'addochat_message_stored', function ( $conversation_id, $message_id, $role, $payload ) {
	// ...
}, 10, 4 );

addochat_providers

FilterSince 0.1.0 Runs in src/Agent/Providers.php.

Filters the AI services of Direct by id. Add your own class that implements \Addochat\Agent\Provider, and add its id to the options of the provider setting with addochat_settings_fields.

Argument	Type	Description
$providers	array<string, \Addochat\Agent\Provider>	Services by id.

add_filter( 'addochat_providers', function ( $providers ) {
	return $providers;
} );

addochat_reply_sent

ActionSince 0.1.0 Runs in src/Chat/Endpoint.php.

Fires after an AI answer was stored.

Argument	Type	Description
$conversation	array<string, mixed>	Conversation row.
$reply	\Addochat\Agent\Reply	The answer.

add_action( 'addochat_reply_sent', function ( $conversation, $reply ) {
	// ...
}, 10, 2 );

addochat_rule_matched

ActionSince 0.2.0 Runs in src/Chat/Endpoint.php.

Fires when a rule matched a visitor message, before its action runs.

Argument	Type	Description
$rule	array<string, mixed>	Rule.
$conversation	array<string, mixed>	Conversation row.
$message_id	int	Visitor message.

add_action( 'addochat_rule_matched', function ( $rule, $conversation, $message_id ) {
	// ...
}, 10, 3 );

addochat_system_prompt

FilterSince 0.1.0 Runs in src/Agent/Prompt.php.

Filters the system prompt of the Direct backend. Keep it the same for every request of a site and language: a stable prompt is cached by the API and costs much less.

Argument	Type	Description
$prompt	string	The system prompt.
$request	Request	The request.

add_filter( 'addochat_system_prompt', function ( $prompt, $request ) {
	return $prompt;
}, 10, 2 );

addochat_visitor_ip

FilterSince 0.1.0 Runs in src/Chat/Token.php.

Filters the IP address used for the visitor rate limit. Behind a proxy without real-IP handling every visitor shares the proxy address; return the forwarded address here when you trust the proxy.

Argument	Type	Description
$ip	string	IP address from REMOTE_ADDR.

add_filter( 'addochat_visitor_ip', function ( $ip ) {
	return $ip;
} );