# Bots

> Build AI-powered agents that connect to MCP workspaces and deploy to Telegram, Discord, WhatsApp, Slack, or any custom endpoint. Two modes — autonomous agent loop and deterministic workflows — with full tool access, identity verification, human handoffs, and multi-bot delegation.

Aerostack Bots are a full agent builder, not just a chatbot. Every bot connects to one MCP workspace and gets instant access to all its tools — databases, payment APIs, ticketing systems, knowledge bases, and anything else you wire up. Two execution modes let you choose exactly how messages are handled: let the LLM figure it out autonomously, or design a deterministic workflow graph that runs exactly the steps you define.

A bot is the interface layer. A workspace is the capability layer. Separate the two and you can swap platforms, models, or tools independently without rebuilding anything.

---

## Architecture

```mermaid
flowchart TD
    A[User sends message] --> B{Platform Adapter}
    B --> |Telegram| C[Normalize to unified format]
    B --> |Discord| C
    B --> |WhatsApp| C
    B --> |Slack| C
    B --> |Custom webhook| C
    C --> D{Mode?}
    D --> |Agent Loop| E[LLM picks tools autonomously]
    D --> |Workflow| F[Execute node graph]
    E --> G[MCP Workspace]
    F --> G
    F --> H[auth_gate / human_handoff / delegate_to_bot]
    G --> I[MCP Server A]
    G --> J[MCP Server B]
    G --> K[Skills / Functions]
    E --> L[Response]
    F --> L
    L --> M[Send reply via platform]
```

Messages arrive from any supported platform, get normalized into a unified format, then enter one of two execution modes. Both modes have full access to every tool in the bot's workspace.

---

## Two Execution Modes

### Agent Loop Mode

The LLM autonomously decides which tools to call, in what order, and when to stop. Best for open-ended conversation, Q&A, and exploratory tasks where you cannot predict every path in advance.

- Up to **10 tool-calling loops** per message (configurable)
- LLM sees all available tools from the workspace and picks the right ones
- Simple messages that need no tools are answered immediately (no tool overhead)
- Works with any LLM provider that supports tool calling

### Workflow Mode

You design a directed graph of nodes and edges. The engine executes them in order, following your branching logic. Best for deterministic processes where every step must happen in a defined sequence.

- Up to **50 nodes per execution** with cycle detection
- **27 node types**: trigger, llm_call, logic, mcp_tool, send_message, action, loop, code_block, agent_loop, confidence_router, guardrail, function_call, auth_gate, schedule_message, send_proactive, delegate_to_bot, structured_output, knowledge_retrieval, wait_delay, sub_workflow, llm_router, memory_store, vision_analyze, document_parse, image_generate, data_transform, parallel
- Variable interpolation across all nodes
- LLM calls available at specific points (structured flow with AI reasoning at key steps)

| | Agent Loop | Workflow |
|---|---|---|
| Control | LLM decides everything | You design the flow |
| Best for | Open-ended chat, Q&A, exploration | Multi-step processes, triage, approvals |
| Tool selection | Automatic (LLM picks) | Explicit (you place `mcp_tool` nodes) |
| Branching | LLM reasons about what to do next | Deterministic if/else, switch, loops |
| Max steps | 10 tool-call rounds | 50 nodes |
| Identity verification | Not available | `auth_gate` node |
| Human approval | Not available | `human_handoff` action |
| Bot-to-bot delegation | Not available | `delegate_to_bot` node |

---

## Supported Platforms

| Platform | Webhook Verification | Auto-Registration | Message Types |
|----------|---------------------|-------------------|---------------|
| [Telegram](/bots/platforms/telegram) | HMAC secret token | Yes (setWebhook API) | Text, callback queries, group chats |
| [Discord](/bots/platforms/discord) | Ed25519 signature | Yes (interactions endpoint + slash commands) | `/ask` and `/reset` slash commands |
| [WhatsApp](/bots/platforms/whatsapp) | HMAC-SHA256 | Partial (manual webhook in Meta Portal) | Text, images, documents, audio, video, location |
| [Slack](/bots/platforms/slack) | HMAC-SHA256 + replay protection | No (manual Event Subscriptions) | DMs, app mentions, channel messages |
| [Custom](/bots/platforms/custom) | None built-in | N/A | JSON `{ text, userId, channelId }` |

---

## LLM Provider Support

| Provider | Models | Tool Calling |
|----------|--------|-------------|
| Anthropic | Claude Opus 4, Claude Sonnet 4, Claude Haiku | Native |
| OpenAI | GPT-4o, GPT-4o Mini, o1 | Native |
| Google | Gemini 2.5 Pro, Gemini 2.5 Flash | Native |
| Groq | Llama 3.3 70B, Mixtral 8x7B | Via OpenAI-compatible API |
| Cloudflare Workers AI | Cloudflare-hosted models | Not supported |
| Custom | Any OpenAI-compatible endpoint | Depends on provider |

You can use Aerostack's pooled API keys (billed via [wallet](/bots/billing)) or bring your own key (BYOK mode, no platform charges).

---

## Key Capabilities

### Workspace Integration

Every bot connects to one MCP workspace. The workspace aggregates tools from multiple MCP servers, Skills, and Functions. Add a Stripe MCP to your workspace and the bot can immediately process payments. Add a database MCP and it can query your data. No code changes needed — the workspace is the single source of capabilities.

### Auth Gate (Identity Verification)

The `auth_gate` workflow node runs a multi-turn identity verification flow directly inside the conversation. The bot prompts the user for their email or phone, sends a one-time code, and verifies it before proceeding. Four built-in providers (Resend, SES, Twilio, MSG91) plus custom HTTP. State machine: `awaiting_contact` to `awaiting_otp` to `verified` or `failed`.

### Human Handoffs

A workflow can pause execution and notify a human reviewer via email, web dashboard, Telegram, or Discord. The reviewer sees the full conversation context, the reason for escalation, and approve/reject buttons. On approval, the workflow resumes down the approved path. On rejection, it follows the rejected path. See [Human Handoffs](/bots/handoffs) for the full guide.

### Bot-to-Bot Delegation

The `delegate_to_bot` node lets one bot call another bot. Each bot can live in its own workspace with its own tools. A reception bot can route to specialist bots (billing-bot, tech-bot, hr-bot) based on intent classification. Maximum 3 delegation hops.

### Proactive and Scheduled Messages

Workflows can send messages to different channels or users (`send_proactive`) and schedule messages for future delivery (`schedule_message`). Use cases: appointment reminders, follow-up messages, shift notifications, daily digests.

---

## Use Cases

### Customer Support (Telegram)

A Telegram bot with a workflow that verifies the customer's identity via `auth_gate`, looks up their order history via a database MCP, checks payment status via Stripe MCP, processes refunds for amounts under $500 automatically, and escalates higher amounts to a finance manager via `human_handoff`. The finance manager approves from their phone and the bot processes the refund.

### Community Manager (Discord)

A Discord bot in agent loop mode connected to a workspace with a knowledge base MCP and a moderation MCP. Users ask questions with `/ask` and the bot searches the FAQ, answers from the knowledge base, and logs unanswered questions for the team to review. Onboards new members with a welcome workflow that collects their role and interests.

### Sales Assistant (WhatsApp)

A WhatsApp bot that qualifies leads through a workflow: asks about company size, use case, and timeline. Scores the lead using a `code_block` node, then either schedules a demo via a calendar MCP or sends product materials. High-value leads trigger a `human_handoff` to the sales team with full context.

### Internal Ops (Slack)

A Slack bot in a company workspace connected to MCPs for metrics dashboards, deployment systems, and incident management. Team members ask "What were yesterday's error rates?" and the bot queries the observability MCP. Deployment requests go through a `human_handoff` to the on-call engineer.

### HR Helpdesk (Slack)

A Slack bot using a workflow to handle PTO requests: verifies employee identity, checks remaining balance via an HR system MCP, submits the request, and routes approval to the employee's manager via `human_handoff`. Also answers benefits questions using a knowledge base MCP in agent loop mode.

### E-commerce Assistant (Telegram)

A Telegram bot for order tracking, returns, and product recommendations. Workflow mode for returns (verify identity, look up order, check return eligibility, process return or escalate). Agent loop mode for general product questions using a catalog MCP.

### Appointment Scheduler (WhatsApp)

A WhatsApp bot that checks availability via a calendar MCP, books appointments, sends confirmation messages, and uses `schedule_message` to send reminders 24 hours and 1 hour before the appointment. Cancellation requests go through a simple workflow that frees the slot and confirms.

### DevOps Incident Bot (Workflow)

A multi-bot setup: a monitoring bot receives alerts, parses severity using an `llm_call` node, and delegates to an `oncall-bot` via `delegate_to_bot`. The oncall-bot creates a PagerDuty incident via MCP, notifies the channel via `send_proactive`, and escalates P1 incidents to the engineering manager via `human_handoff`.

---

## Aerostack vs Other Bot Builders

| Feature | Aerostack | Botpress | Voiceflow |
|---------|-----------|----------|-----------|
| Execution modes | Agent loop + workflow graph | Flow-based + "autonomous" nodes | Canvas flow-based |
| Tool access | Full MCP workspace (any MCP, Skill, or Function) | Built-in integrations + custom API calls | API steps + integrations |
| LLM providers | 6 providers, BYOK supported | OpenAI only (default) | OpenAI, Anthropic |
| Identity verification | Built-in `auth_gate` (OTP, magic link, 4 providers) | Custom flow required | Custom flow required |
| Human handoffs | Native workflow node with multi-channel notification | Handoff to live agent (Zendesk, etc.) | Not built-in |
| Bot delegation | `delegate_to_bot` with 3-hop routing | Not available | Not available |
| Platforms | Telegram, Discord, WhatsApp, Slack, Custom | Web, WhatsApp, Telegram, Messenger | Web, WhatsApp, Telegram, custom |
| Hosting | Cloudflare edge (global, no cold starts) | Botpress Cloud | Voiceflow Cloud |
| Pricing | Pay-per-use wallet or BYOK | Per-message + plan tiers | Per-interaction + plan tiers |
| Open protocol | MCP (open standard) | Proprietary integrations | Proprietary integrations |

The key difference: Aerostack bots inherit capabilities from the MCP ecosystem. Any MCP server anyone publishes — open source or on the Aerostack marketplace — immediately becomes a capability your bot can use. No custom integration code.

---

## Billing Modes

| Mode | How It Works |
|------|-------------|
| **Wallet** | Prepaid balance, auto-deduct per conversation |
| **BYOK** | Bring your own LLM API key. No platform charge. |
| **Plan Quota** | Coming soon. Included usage within your account plan. |

See [Billing & Limits](/bots/billing) for pricing details, spending caps, and rate limits. See [Cost Optimization](/bots/cost-optimization) for strategies to reduce costs.

---

## Next Steps

- [Create Your First Bot](/bots/create-first-bot) — Step-by-step dashboard tutorial
- [Platform Guides](/bots/platforms/telegram) — Set up Telegram, Discord, WhatsApp, Slack, or custom webhooks
- [Connect Tools](/bots/connect-tools) — Give your bot capabilities through workspaces
- [Workflows](/bots/workflows) — Design deterministic automation flows
- [Human Handoffs](/bots/handoffs) — Pause for human approval
- [Bot Teams & Delegation](/bots/bot-teams) — Route between specialist bots