Actions

What are actions?

Actions let your AI assistant do things beyond answering questions: send emails, create tickets, update CRM records, book meetings, trigger webhooks, and more.

Every action in comxbot is typed, logged, and governed. Unlike simple API calls, actions go through a structured approval flow that gives you full control and audit trail.

Actions are defined per-assistant. You specify what the assistant can do, what parameters it needs, and what approval rules apply.

Built-in actions cover common use cases: send email, create calendar event, submit form, update record. Custom webhook actions let you integrate with any external system.

Actions are only triggered when the conversation context warrants it. The assistant proposes an action based on user intent, not on predefined flows.

Creating action definitions

Navigate to the assistant's Actions tab and click New Action. Each action definition includes:

Name and description: A clear name (e.g. 'Book Meeting') and description of what it does. The assistant uses the description to decide when to propose the action.

Parameters: Define the inputs the action needs. Each parameter has a name, type (string, number, email, date, enum), description, and whether it's required.

Approval mode: Choose from Auto-Approve (executes immediately), Requires Approval (human must approve), or Dry-Run First (simulate before approval).

Webhook URL: For custom actions, provide the endpoint to call when the action executes. Comxbot sends a POST with action parameters and conversation context.

Validation rules: Add constraints on parameters (regex patterns, min/max values, allowed values). Invalid proposals are rejected before reaching approval.

Rate limits: Set maximum executions per hour/day per user or globally. Prevents runaway action loops.

The approval flow (propose, dry-run, approve, execute)

Comxbot's action framework follows a four-stage process for maximum safety and transparency:

Stage 1 - Propose: The assistant identifies that an action should be taken and proposes it with specific parameters. Example: 'I would like to send an email to john@example.com with subject: Meeting follow-up'. The proposal is shown to the user for confirmation.

Stage 2 - Dry-Run (optional): If enabled, the action is simulated without real side effects. The dry-run result shows what would happen. Example: 'Dry-run result: Email would be sent to john@example.com via SendGrid. No actual send performed.'

Stage 3 - Approve: A human (either the end-user or an admin, depending on configuration) approves the action. For auto-approve actions, this stage is skipped.

Stage 4 - Execute: The action is executed for real. Results are logged, the user is informed of the outcome, and the action appears in the audit trail.

If any stage fails, the assistant informs the user and can offer alternatives. Failed actions are logged with error details for debugging.

The entire proposal-to-execution chain is stored in the audit trail with timestamps, actor IDs, and full parameter snapshots.

Built-in actions vs custom webhooks

Built-in actions: Comxbot provides pre-built actions for common operations. These are tested, monitored, and maintained by the platform.

Available built-in actions: Send Email (via your connected SMTP or SendGrid), Create Calendar Event (Google Calendar, Outlook), Submit Form (internal form submission), Create Ticket (Zendesk, Linear, Jira via integration), and Update CRM (HubSpot, Salesforce via integration).

Custom webhooks: For anything not covered by built-in actions, create a custom webhook action. You provide the endpoint URL, and comxbot sends a structured payload.

Webhook payload includes: action name, parameters (as defined), conversation ID, user info (if available), and a signature header for verification.

Webhook responses: Your endpoint should return a JSON response with a 'success' boolean and optional 'message' string. The message is shown to the user.

Security: All webhooks are called over HTTPS. You can verify the request signature using your webhook secret (provided in Settings). Unsigned requests should be rejected.

Retry policy: Failed webhook calls are retried up to 3 times with exponential backoff. After all retries fail, the action is marked as failed and the user is notified.