Confirmation flows & audit log

Some actions are safe to fire automatically (look up an order). Others should never run without a human saying yes (cancel an order, refund a customer). The framework supports both, and it records every call either way.

In this guide:

• When to require confirmation
• How the confirmation UX works
• The audit log
• Filtering and exporting

When to require confirmation

Mark an action requires_confirmation: true when any of these are true:

• The action modifies external data (cancel order, update record, send email).
• The action costs money (refund, charge, purchase).
• The action sends a message to a real person (post Slack, send SMS, email).
• The action gives access (grant permission, invite user).

Read-only actions (look up status, fetch records) are usually safe without confirmation.

How confirmation works

When the bot decides to call a confirmation-gated action:

1. The bot generates the parameters from the conversation.
2. Instead of firing, it renders an inline confirmation card in chat with: action name, parameters, expected effect, Confirm and Cancel buttons.
3. The user clicks Confirm.
4. The action fires.
5. The bot uses the response to continue the conversation.

If the user clicks Cancel (or doesn’t respond), the action does not fire. The conversation continues as if the bot had asked a regular question.

Screenshot: A confirmation card in chat for a destructive Stripe action.

Confirmation in the agent dashboard

For sensitive actions you want a human teammate (not the customer) to approve, configure the action to escalate confirmation:

• The bot pauses execution.
• A notification posts to your support Slack channel (if connected) with Approve / Reject buttons.
• An assigned agent reviews and decides.
• The conversation resumes with the action fired (Approve) or skipped (Reject).

This pattern is great for high-value moves: refunds above a threshold, custom enterprise discount codes, account merges.

The audit log

Every action call — confirmed, rejected, or auto-fired — is recorded.

Screenshot: The action audit log with timestamps, status, and payload.

Each row contains:

• Timestamp — when the call started.
• Action — which action ran.
• Status — success / failed / pending_confirmation / rejected.
• Parameters — what the bot sent (sensitive fields redacted).
• Response — HTTP status, response body summary.
• Conversation — link to the conversation that triggered it.
• User / Agent — the human who confirmed (or “auto” if no confirmation gate).
• Duration — wall time for the call.

Open the audit log

On the chatbot detail page → Actions → click any action → Audit log tab. Or for a global view, Settings → Activity filtered by action.executed.

Filtering

The audit log supports filters:

• By status: see failed calls only to debug.
• By time range: last hour, last 24h, custom.
• By conversation: trace every action one specific user triggered.
• By action: see only Stripe-cancel calls.

Exporting

Click Export → CSV to download the filtered audit log. Useful for monthly reporting or compliance audits.

Compliance and PII

The audit log respects your PII policies:

• User-supplied freeform text in destructive actions (e.g., the body of an order note) is not logged to plaintext — only metadata (action name, target ID, mode) is.
• Sensitive fields in payloads (password, apiKey, secret*) are auto-redacted before logging.

For stricter requirements, audit log retention can be adjusted on Enterprise plans.

Tips

• Default to requires_confirmation: true. It’s easier to relax than to recover from an accidental refund storm.
• Write clear confirmation card descriptions. “Cancel order #1234 for John Smith — total $89.50?” beats “cancel_order(1234)”.
• Review the audit log weekly. Look for failed actions, accidental fires, and patterns the bot misuses.

What’s next