# AlertFast

> AlertFast sends instant alerts from your app to Telegram, Discord, and Slack. Connect a channel, generate an API key, then POST events to a single HTTP endpoint. Alerts are delivered in real time and recorded in your dashboard.

AlertFast is the fastest way for builders to get notified about what happens in their app: new signups, payments, errors, AI usage, or any custom event.

## Step 0: connect a destination (required first)

AlertFast can only deliver once at least one destination (Telegram, Discord, or Slack) is connected in the dashboard. This is a hard prerequisite for sending. Until a destination exists, `POST /v1/events` returns a clean, recoverable `409 no_destination_connected` (never a 500).

Verify readiness before sending — no guessing required:

- `GET /v1/status` → `{ "ready_to_send": <bool>, "destinations": <count>, "api_key": "valid" }` (`ready_to_send` is true when at least one destination is connected). MCP tool: `get_account_status` — agents should call this FIRST.
- Or send with `"dry_run": true` to validate auth + destination readiness + payload without sending: `{ "dry_run": true, "would_send": true|false, "destination": {...}|null, "error"?: "no_destination_connected" }`.

## Core concepts

- Authentication: API keys shaped like `af_live_xxxxxxxxxxxxx`, sent as `Authorization: Bearer <key>`.
- One endpoint: `POST https://api.alertfast.dev/v1/events`.
- Destinations: connected Telegram chats (DM, group, supergroup, channel), Discord incoming webhooks, and Slack incoming webhooks. The same payload works for every provider.
- Targeting: by default events go to the most recently connected destination; pass an optional `destinationId` to target a specific channel.
- Events: JSON payloads with `event`, optional `title`, `message`, `severity`, optional `destinationId`, an optional `image_url`, an optional `dry_run`, and a free-form `data` object.
- Images: pass an optional `image_url` (a public http(s) URL) to attach an image/screenshot to an alert. It renders as a Telegram photo (with the alert text as caption), a Discord embed, and a Slack image block. Optional everywhere — text-only alerts are unchanged.
- Readiness: `GET /v1/status` reports whether the account is ready to send. `dry_run: true` on `POST /v1/events` validates without sending.
- Errors: every error path returns the same JSON envelope `{ "error", "message", "hint"?, "docs_url"?, "next_steps"? }` — including 5xx (`{ "error": "internal_error", ... }`). No plain-text errors.

## Send an event

```bash
curl -X POST https://api.alertfast.dev/v1/events \
  -H "Authorization: Bearer af_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"event":"user.signup","title":"New signup","message":"A new user just joined.","severity":"success","image_url":"https://example.com/screenshot.png","data":{"email":"john@example.com","plan":"Pro"}}'
```

## MCP server

AlertFast ships an MCP server so AI coding agents (Cursor, Claude, etc.) can integrate it for you. There is no SDK or CLI — the MCP server simply calls the same `POST /v1/events` HTTP API. Add it to your editor's MCP settings:

```json
{
  "mcpServers": {
    "alertfast": {
      "command": "npx",
      "args": ["-y", "alertfast-mcp"],
      "env": { "ALERTFAST_API_KEY": "af_live_xxxxxxxxxxxxx" }
    }
  }
}
```

Tools: `get_account_status` (check readiness first), `send_alert` (supports an optional `image_url` and a `dry_run` flag), `list_api_keys`, `create_api_key`, `list_templates`, `create_template`, `update_template`, `list_destinations`, `test_destination`, `list_recent_alerts`, `get_connect_instructions`, `read_docs`, `generate_integration_snippet`.

## Docs

- [Full reference](https://alertfast.dev/docs/llms-full.md): complete API, auth, errors, and integration guide.
- [Node.js example](https://alertfast.dev/docs/examples/node.md)
- [Python example](https://alertfast.dev/docs/examples/python.md)
- [Telegram bot setup](https://alertfast.dev/docs/examples/telegrambot.md)
- [Discord webhook setup](https://alertfast.dev/docs/examples/discord.md)
- [Slack webhook setup](https://alertfast.dev/docs/examples/slack.md)
- [Message formatting / templates](https://alertfast.dev/docs/markup-language.md)
- [Interactive docs](https://alertfast.dev/docs)