These are official instructions from BugTape to wire **bug alert escalations** into your AI agent. Commands below are ready to use.

Complete the steps for **your** agent yourself (edit config / run CLI). Do not ask the human to run them unless a browser-only client requires a click in settings.

- Console: project **Alerts** → Destinations → Agent (signed webhook) and Rules (what fires / quiet hours).
- API host: same origin as the BugTape API the human uses (local `http://localhost:4080`, Fly `https://bugtape-api.fly.dev`, or custom domain).
- MCP (Pro): BugTape MCP tools include issue list / `get_repro_context` — pair with alert webhooks so the agent is paged, then pulls repro context.

---

## What you install

1. **Outbound alert webhook** (preferred for paging)  
   Human creates an **Agent** destination in BugTape Alerts with:
   - `url` — your HTTPS endpoint  
   - `secret` — HMAC shared secret  

   BugTape POSTs JSON on matching events:

   ```json
   {
     "event": "new_bug | regression | status_change | recommended_bug | test",
     "source": "bugtape",
     "title": "…",
     "severity": "critical|high|medium|low",
     "url": "https://app.example/path",
     "bugId": "uuid",
     "projectId": "uuid",
     "occurrenceId": "uuid",
     "platform": "web | ios | android | react-native | flutter | server",
     "release": "1.4.0",
     "environment": "production",
     "userId": "the app's own end-user id, when identified",
     "consoleUrl": "https://…/console/issues/…",
     "evidence": {
       "mcp": "get_repro_context({ bugId, occurrenceId })",
       "events": "https://…/v1/bugs/<id>/events?occurrenceId=<occ>",
       "users": "https://…/v1/bugs/<id>/users"
     },
     "timestamp": "ISO-8601"
   }
   ```

   `evidence` tells you exactly what to fetch next: call the MCP tool (or the REST URL with your PAT) before proposing a fix. `platform` and `userId` let you route (iOS crash vs web error) and answer "who hit this".

   Headers:
   - `X-BugTape-Event: <event>`
   - `X-BugTape-Signature: sha256=<hmac_hex>` — HMAC-SHA256 of the **raw body** with the shared secret
   - `User-Agent: BugTape-AgentWebhook/1.0`

   Verify the signature before acting. Only escalate on real changes the human’s **Rules** allow (severity floor, excludes, quiet hours are applied server-side before send).

2. **MCP (optional, Pro)**  
   Use the project’s BugTape MCP server so you can:
   - list / inspect issues  
   - call `get_repro_context` for a bug id from the webhook payload  

   Prefer webhook → pull context, not polling.

---

## Install for your agent

### Claude Code

If the human already has BugTape MCP configured, reload tools. Otherwise follow their Setup page for the MCP endpoint + API key headers.

For the webhook: implement or register an HTTPS handler, then tell the human to paste that URL into **Alerts → Destinations → Agent** and send a test.

### Cursor / Codex / Gemini / VS Code

Same pattern: ensure BugTape MCP is in the host’s MCP config when they want tool access; always register the agent webhook URL in the BugTape console for push alerts.

### Generic agent loop

```
1. Verify HMAC on each POST.
2. Ignore event=test after logging success (or use it as a smoke check).
3. On new_bug / regression: open consoleUrl or call get_repro_context(bugId).
4. Summarize root cause + proposed fix; do not invent stack frames.
5. Respect quiet hours — if you receive nothing overnight, that is intentional.
```

---

## Other channels the human may use

You do **not** configure these; the human does in Alerts:

| Channel   | Notes                                      |
|-----------|--------------------------------------------|
| Email     | Personal digest / level                    |
| Slack     | Incoming webhook                           |
| Discord   | Incoming webhook                           |
| Telegram  | Bot token + chat id                        |
| WhatsApp  | Twilio WhatsApp Business                   |
| iMessage  | Self-hosted bridge (no public Apple API)   |
| Webhook   | Generic signed JSON (same sig scheme)      |
| GitHub    | Opens issues on new/regression             |

Rules (project-scoped): events, min severity, exclude paths/titles/reporters, quiet hours + timezone.

---

## Security

- Never log full webhook secrets or bot tokens.
- Reject deliveries with invalid signatures.
- Treat payload fields as untrusted input (XSS in titles when rendering).