# Templates — Bots

> Bot templates — pre-built configurations with system prompts, suggested MCPs, and optional workflows.

Bot templates are pre-built configurations that bundle a system prompt, suggested MCP servers, and optional workflows. Templates let you create a fully configured bot in one step instead of building from scratch.

---

## System Templates

Aerostack ships with three built-in system templates. These cannot be modified or deleted.

| Template ID | Name | Category | Suggested MCPs | Has Workflow |
|-------------|------|----------|----------------|-------------|
| `tpl_support` | Customer Support | support | Zendesk, Stripe | Yes |
| `tpl_community` | Community Manager | community | *(varies)* | Yes |
| `tpl_sales` | Sales Assistant | sales | *(varies)* | Yes |

Each system template includes a pre-built `workflow_json` graph optimized for its use case.

---

## Using a Template

### Via the Setup Wizard (Recommended)

The setup wizard creates everything in one API call — workspace, MCP connections, and bot:

```bash
curl -X POST https://api.aerostack.dev/api/bots/setup \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_support",
    "bot_name": "Acme Support Bot",
    "platform": "telegram",
    "platform_config": {
      "bot_token": "123456:ABC..."
    },
    "config_values": {
      "company_name": "Acme Corp",
      "support_hours": "9am-5pm EST",
      "refund_policy": "30-day money-back guarantee"
    }
  }'
```

The `config_values` object is injected into the template's system prompt. Each key-value pair is appended as context:

```
Context - company name: Acme Corp
Context - support hours: 9am-5pm EST
Context - refund policy: 30-day money-back guarantee
```

Config values are sanitized to prevent prompt injection. Keys must match `[a-zA-Z0-9_]` (max 50 characters). Values are capped at 500 characters and stripped of known injection patterns.

### Via the Dashboard

1. Navigate to **Bots** > **New Bot**
2. Browse available templates
3. Select a template and fill in your customizations
4. The wizard creates the workspace and bot automatically

---

## Listing Templates

Templates are publicly accessible (no auth required):

```bash
# List all templates
curl https://api.aerostack.dev/api/bots/templates

# Filter by category
curl "https://api.aerostack.dev/api/bots/templates?type=support&limit=10"
```

Response:

```json
{
  "templates": [
    {
      "id": "tpl_support",
      "name": "Customer Support",
      "description": "AI-powered customer support bot with ticket creation and order lookup.",
      "category": "support",
      "system_prompt": "You are a helpful customer support agent for {{company_name}}...",
      "suggested_mcps": "[\"zendesk\", \"stripe\"]",
      "popularity": 150
    }
  ]
}
```

Get a single template:

```bash
curl https://api.aerostack.dev/api/bots/templates/tpl_support
```

---

## Creating Custom Templates

Create your own templates to reuse across bots or share with your team.

```bash
curl -X POST https://api.aerostack.dev/api/bots/templates \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IT Helpdesk",
    "description": "Internal IT support bot for employee technical issues.",
    "category": "support",
    "system_prompt": "You are an IT helpdesk assistant. Help employees with technical issues. Common solutions:\n1. Password resets: Direct them to the password reset portal at {{reset_url}}\n2. VPN issues: Ask them to restart the VPN client\n3. Hardware issues: Create a support ticket",
    "suggested_mcps": ["jira", "ldap"],
    "llm_config": {
      "temperature": 0.3
    },
    "icon_url": "https://example.com/helpdesk-icon.png"
  }'
```

Response:

```json
{
  "template": {
    "id": "tpl_a1b2c3d4e5f6g7h8",
    "name": "IT Helpdesk",
    "owner_id": "user_abc123",
    "category": "support",
    "popularity": 0
  }
}
```

---

## Updating Custom Templates

You can only update templates you own. System templates (where `owner_id` is null) cannot be modified.

```bash
curl -X PATCH https://api.aerostack.dev/api/bots/templates/tpl_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "suggested_mcps": ["jira", "ldap", "confluence"]
  }'
```

---

## Deleting Custom Templates

```bash
curl -X DELETE https://api.aerostack.dev/api/bots/templates/tpl_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Deleting a template does not affect bots that were created from it. Existing bots retain their configuration independently.

---

## Template Permissions

| Action | System Templates | User Templates |
|--------|-----------------|----------------|
| List / View | Anyone | Anyone |
| Create | N/A | Authenticated users |
| Update | Blocked (403) | Owner only |
| Delete | Blocked (403) | Owner only |

System templates are built-in and immutable.

---

## Template Fields Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Template display name |
| `description` | Yes | Brief description of the template's purpose |
| `category` | Yes | Category for filtering (`support`, `community`, `sales`, etc.) |
| `system_prompt` | Yes | The LLM system prompt. Can include `{{placeholder}}` variables. |
| `suggested_mcps` | No | JSON array of MCP server slugs to auto-connect. Default: `[]` |
| `llm_config` | No | Default LLM config (e.g., `{ "temperature": 0.3 }`). Default: `{}` |
| `workflow_json` | No | Pre-built workflow graph. If provided, the bot can enable workflow mode. |
| `icon_url` | No | URL to an icon for display in the template gallery |

---

## Best Practices

1. **Write system prompts with placeholders.** Use `{{company_name}}`, `{{product}}`, etc. so the setup wizard can customize them per deployment.

2. **Include specific MCP suggestions.** The setup wizard resolves MCP server slugs and connects them automatically. Only suggest MCPs that are published and available.

3. **Keep system prompts focused.** A good template prompt describes the bot's role, key behaviors, and when to use specific tools. Avoid generic instructions.

4. **Test before sharing.** Create a bot from your template using the setup wizard to verify that the MCP connections and system prompt work as expected.