Actions Overview

Actions Overview

Most AI agents answer questions. With Actions, your Chatsby agent can do things — execute tasks, call external APIs, collect structured data from users, and trigger workflows in real time, all without leaving the conversation.

Actions transform your agent from a static knowledge base into a dynamic assistant that drives business outcomes. Instead of saying "please email [email protected] for order status," your agent can ask for the order number, call your backend, and return tracking information in seconds.

What Are Actions?

An Action is a defined task that your AI agent can perform when specific conditions are met during a conversation. Each action consists of three components:

1. Trigger condition — A natural-language description that tells the agent when to activate the action.
2. Parameters — The information the agent must collect from the user before execution.
3. Execution — The operation performed once all parameters are gathered (API call, webhook, internal process).

When a user's message matches a trigger condition, the agent shifts from answering questions to collecting the required parameters through natural conversation. Once all parameters are gathered, the action executes and the agent delivers the result.

Real-World Examples Across Industries

Actions are designed to be flexible enough for any business workflow. Here are examples of how teams across different industries use them:

Action Execution Flow

Every action follows the same predictable lifecycle. Understanding this flow helps you design actions that feel natural and deliver reliable results.

User sends a message
        │
        ▼
┌─────────────────────────┐
│  Agent evaluates message │
│  against trigger          │
│  conditions               │
└─────────┬───────────────┘
          │ Match found
          ▼
┌─────────────────────────┐
│  Agent begins parameter  │
│  collection via natural  │
│  conversation            │
└─────────┬───────────────┘
          │ All required params collected
          ▼
┌─────────────────────────┐
│  Chatsby sends webhook   │
│  POST request with       │
│  parameters + metadata   │
└─────────┬───────────────┘
          │ Response received
          ▼
┌─────────────────────────┐
│  Agent formats response  │
│  and delivers result to  │
│  the user                │
└─────────────────────────┘

Key points about the execution flow:

• Parameter collection is conversational. The agent does not present a rigid form. It asks for each parameter naturally, one at a time or in logical groups, adapting to what the user has already provided.
• Validation happens in real time. If a user provides an invalid email address or a number where text is expected, the agent prompts them to correct it before proceeding.
• Execution is synchronous. Your webhook has up to 30 seconds to respond. If it times out, the agent delivers a configurable fallback message.

Built-in Actions

Chatsby provides three pre-built actions that cover the most common use cases. These require no webhook configuration and work out of the box on all plans.

Lead Capture

The most popular action. When a visitor expresses interest — asking for a demo, requesting pricing, or wanting to be contacted — the agent collects their information and stores it as a contact in your Chatsby dashboard.

Human Escalation

Some conversations require a human touch. The Human Escalation action allows your agent to recognize when it cannot help and hand the conversation off to your team.

Feedback Collection

Gather structured feedback about the conversation experience. This action activates at the end of conversations or when explicitly triggered.

Custom Actions

When built-in actions are not enough, custom actions let you connect your agent to any external system with an HTTP API. Custom actions are the way to build truly differentiated agent experiences.

With custom actions, you can:

• Query databases — Look up orders, accounts, inventory, or any record in your system.
• Trigger workflows — Start processes in your CRM, ticketing system, or marketing automation platform.
• Perform calculations — Send data to your backend for processing and return computed results.
• Create records — Book appointments, submit applications, create support tickets.
• Integrate with third-party APIs — Connect to Stripe, Twilio, Calendly, or any service with a REST API.

Prerequisites for custom actions:

1. An HTTP endpoint (webhook URL) that can receive POST requests and return JSON responses.
2. A Chatsby account on a paid plan (Pro, Business, or Enterprise).
3. A clear understanding of what data your endpoint needs and what it returns.

Plan Availability

When to Use Actions (and When Not To)

Actions are powerful, but they are not always the right solution. Here is a quick guide:

Use actions when:

• The user needs a specific result from an external system (order status, account balance, booking confirmation).
• You need to collect structured data in a conversational format (lead forms, surveys, intake questionnaires).
• A conversation should trigger a process in another system (CRM update, ticket creation, notification).

Keep it simple when:

• The information is already in your agent's training data. If the answer exists in your sources, the agent can answer directly without an action.
• The workflow is too complex for a single webhook call. If the process requires multiple sequential steps with branching logic, consider building that logic in your backend and exposing a single endpoint.
• The user experience does not benefit from real-time execution. If results take minutes or hours, it may be better to collect contact info and follow up.

Security Considerations

Actions involve passing user data to external systems, so security is a core concern.

• Data in transit. All webhook calls from Chatsby are made over HTTPS. HTTP endpoints are not supported.
• Authentication. Custom actions support Bearer token authentication and custom headers, so you can verify that incoming requests originate from Chatsby.
• Parameter scoping. Actions only have access to the parameters explicitly defined in the action configuration and conversation metadata (conversation ID, agent ID). They cannot access your full contact database or other agents' data.
• No credential storage. Chatsby does not store API keys or tokens in logs. Authentication headers are encrypted at rest and only decrypted at execution time.
• Webhook validation. You can verify incoming requests by checking the X-Chatsby-Signature header, which contains an HMAC-SHA256 signature of the payload using your webhook secret.

Next Steps

• Creating Actions — Build your first custom action with a step-by-step guide, including full webhook code examples.
• Managing Contacts — Learn how to work with leads captured by the Lead Capture action.
• Playground — Test your actions in a safe sandbox before deploying to production.