Build actions that deserve to run

Side effects

An action crosses the boundary between talking and doing.

Email can notify a real inbox. A webhook can query or change another service. A WordPress Hook can run custom site behavior. Configure the smallest action, make the destination defend itself, and describe success as precisely as the evidence allows.

Before the fields: understand when actions can run

In Basic runtime, an enabled action assigned to the active Assistant may run when the model calls it with acceptable arguments. There is no separate plugin-enforced visitor approval step. The conversation can collect required values, but that is not the same as a guaranteed confirmation screen.

In Advanced Agents runtime, an action must also be connected to the specialist in the published flow. Email, non-GET webhook, and WordPress Hook actions are classified as side effects and pass through the advanced approval policy and duplicate-action guard. The visitor can be asked for explicit approval before execution. GET webhooks are treated as live-data lookup rather than side effects.

Design for the runtime that offers less protection

The administrator can turn Advanced Agents off. Do not make a dangerous action broadly available in Basic runtime and rely on the Advanced approval experience to save it. Restrict assignment, scope, receiver permissions, and impact.

Email: a message, not proof of delivery

The Email Tool builds an HTML message and passes it to WordPress wp_mail(). Newlines in the configured body are converted for HTML display. A true result means the WordPress mail system accepted the request; it does not prove the recipient’s server accepted it, that it avoided spam, or that a person read it.

Every Email action field

Field	Behavior	Production guidance
To	Fixed recipient saved in Tool configuration.	Use a monitored role inbox or sandbox address. Keep visitor input out of the destination.
CC	Optional template; parameter placeholders can be substituted.	Prefer fixed reviewed recipients. Dynamic addresses widen disclosure risk and need deliberate testing.
Subject	Template with named parameter placeholders.	Keep personal or sensitive detail out of subject lines, which appear widely in mail systems.
Body	HTML email content with placeholder substitution and line-break conversion.	Label each value, include operational context, and escape expectations at downstream systems.
Reply-To	Optional template; the final substituted value is validated as an email address.	Use the visitor’s validated reply email only when the workflow genuinely needs direct replies.
Parameters	Supply dynamic values used in templates.	Require only execution blockers; the receiver still owns length, consent, abuse, and business rules.
Success / Error response	Returns configured feedback around the Tool outcome.	Say “Your request was submitted for sending,” not “Our team received and will answer today” unless another system proves that.

Configure WordPress mail delivery before launch and monitor failures at the mail provider. A successful admin test verifies the Tool path, not long-term deliverability.

Webhook: a real HTTP request from your website

A webhook makes an outbound request from the WordPress server with a 15-second timeout. GET adds arguments to the query string. POST supports JSON object, form URL encoded, raw text, or no body. A 2xx HTTP response is considered transport success; non-2xx is failure. When a successful response contains JSON, the decoded value can return to the model; otherwise the raw body can return.

Webhook configuration

Field	What SmartSite sends	What to verify
URL	A fixed configured endpoint.	Public HTTPS, correct environment, narrow route, no visitor-controlled destination.
Method	GET or POST.	Use GET only for a genuinely read-only lookup. Use POST for submission/change, with receiver authorization.
Custom Headers	A JSON object merged into request headers.	Valid JSON, minimum secrets, a rotation plan, and no secrets exposed in screenshots or errors.
POST Body Format	JSON object, form URL encoded, raw text, or no body.	Match the receiver’s documented contract exactly.
JSON Body Template	Chosen JSON structure with parameter placeholders; an empty template sends all arguments.	Send only needed fields. Exact-value placeholders can preserve number/boolean types.
Raw Body Template	Plain text with named placeholder replacement.	Avoid when structured JSON can be validated more reliably.
Allow unsafe HTTP	Uses ordinary WordPress remote requests instead of safe URL validation.	Leave off in production. It can permit private/internal targets and weaken SSRF protection.

The default safe request functions reject unsafe URLs and network targets. The Allow unsafe HTTP checkbox exists for intentional controlled development/private-network situations; checking it bypasses those WordPress URL-safety protections. It is not required for an ordinary public HTTPS API.

When an Advanced flow uses a webhook with this bypass, Flow Checks surface a warning. Publishing can proceed only through the deliberate warning confirmation described in the Agentic Flow guide. That ability to publish anyway does not reduce the network risk.

A webhook receiver must distrust the request

Authenticate the calling site, validate every field, authorize the exact operation, limit rate and payload size, reject unexpected keys, and use an idempotency strategy. A Tool Description influences model choice; it does not prove who the visitor is.

WordPress Hook: a contract with custom code

Despite the interface language “Action/Filter Name,” runtime calls a namespaced WordPress filter:

smartsite_tool_{configured_name}

The callback receives the initial value null and the argument array. A developer must register the exact filter and return a serializable useful result. If no callback changes the initial value, the Tool can still report a generic “Action executed” success path. That means an admin test must verify the intended side effect or returned value—not merely trust the absence of an error.

The WordPress Hook agreement

Responsibility	Administrator	Developer
Name	Choose the agreed suffix in the Tool.	Register the exact smartsite_tool_ prefixed filter.
Arguments	Define names, types, descriptions, and required values.	Validate shape, permission, ownership, allowed values, and limits again.
Operation	Describe the narrow visitor outcome.	Implement only that outcome; do not expose a generic command dispatcher.
Result	Write honest success/error wording.	Return a safe serializable result or a controlled error; never return secrets or raw internals.
Duplicates	Test repeated conversation requests.	Make side effects idempotent or detect duplicate operation keys.

Build an action in widening circles

1. Define the maximum allowed effect. One callback request, one read-only availability query, one approved status change—not a general integration gateway.
2. Choose a sandbox destination. Use a test inbox, staging endpoint, or development callback with synthetic records.
3. Create the parameter contract. Keep permissions and destinations fixed; require only real inputs.
4. Configure while disabled. Review URL, method, headers, recipients, templates, assignments, and messages.
5. Test the transport. Run the admin test once and inspect the real inbox, endpoint log, or WordPress state.
6. Test failure truthfully. Return non-2xx, timeout, invalid email, missing required field, rejected authorization, and duplicate operation.
7. Test in Basic chat. Confirm the Tool does not run for informational, ambiguous, or merely hypothetical language.
8. Test in Advanced flow if used. Confirm specialist assignment, visitor approval, cancellation, and duplicate protection.
9. Enable narrowly. Monitor Chat History and receiver logs; keep a rollback/disable owner available.

Result language is part of safety

“Success” means the local implementation accepted its layer’s result. For email it is mail-system acceptance. For webhook it is a 2xx response, even if a poorly designed API returns business failure inside a 200 body. For a Hook it is the callback/result path, which must be verified by custom code behavior.

Use messages that match those facts. “Request submitted” is safer than “Appointment booked” unless the endpoint returns a validated booking identifier and the receiving system guarantees the state change. Avoid putting remote response bodies into visitor errors; they may contain implementation details.

Rehearse cancellation and uncertainty

An action experience is not complete if only an enthusiastic “yes” works. In Advanced runtime, test that the visitor can cancel the approval prompt without a side effect and can revise details before approving. In Basic runtime, test ambiguous language such as “I might ask for a callback” and confirm it does not become a submission.

When the remote outcome is uncertain—a timeout after the receiver may have processed the request—do not automatically invite immediate repetition. Use an operation identifier at the receiver, check status where possible, and give the visitor cautious language. Otherwise a network failure can turn into two successful real-world actions.

Review the webhook screen

tools-action-tools

Screenshot capture pending /images/screenshots/tools/action-tools.webp

Email, Webhook, and WordPress Hook Actions

Capture

Show a sanitized Webhook Action form with an example.invalid HTTPS URL, POST selected, safe targets enforced, and Enabled off.

Show

URL, method, headers JSON, private-target toggle, parameters, Test, Enabled

Viewport

Desktop, 1440 × 900

Annotate

Use numbered callouts only for controls referenced in the procedure.

Redact

OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text

Before production

• Validate inputs with the parameter contract.
• Run the preset and test ladder.
• Complete the security preflight and incident playbook.
• For Advanced routing and approval behavior, read capabilities and safe exits.