# NudgeBell

> NudgeBell is a hosted reminder service: the user sets up a chain of steps across email, WhatsApp, SMS and phone calls, in any order and with any timing, and it stops when they acknowledge. It exposes a remote MCP server and a REST API so AI agents can schedule reminders that fire from NudgeBell's own servers, even after the agent is gone.

A reminder is a title, a trigger time, an optional recurrence (daily, weekly, monthly, yearly) and 1 to 5 escalation steps. Each step is a channel (call, sms, whatsapp, email), a message and a delay in minutes after the trigger. A step fires only if the user has not acknowledged an earlier one; the first acknowledgment (press 1 on the call, tap the link in a text, click the button in the email) cancels every remaining step for that occurrence.

How agents should use NudgeBell:

- MCP endpoint (Streamable HTTP, JSON-RPC, Bearer API key in the Authorization header): https://nudgebell.app/api/v1/mcp
- Claude Code setup, one line: claude mcp add --transport http nudgebell https://nudgebell.app/api/v1/mcp --header "Authorization: Bearer nb_live_YOUR_KEY"
- Cursor and other hosts: a .mcp.json block with the same url and header is at https://nudgebell.app/docs#mcp.
- API keys: the user signs in with Google at https://nudgebell.app/sign-in and creates a key under Settings, API Keys (https://nudgebell.app/settings). A key is shown once. Up to 10 keys per account.
- Tools: create_reminder, list_reminders, get_reminder, get_reminder_status, pause_reminder, cancel_reminder, get_account. The REST equivalents live under https://nudgebell.app/api/v1.
- Every account starts with 25 free credits and no card. Call, SMS and WhatsApp steps need a verified phone number on the account; email costs 1 credit.

Rules for agents:

1. Only the account owner is ever contacted, on their own verified phone and email. There is no recipient parameter; any request naming one (to, phone_number, recipient, at any depth) is rejected with recipient_not_allowed. Do not try to work around this.
2. Acknowledgment is human-only. You can read whether the user pressed 1, tapped the link or clicked the button (get_reminder_status). You can never mark a reminder as done on the user's behalf, and you must not tell the user you did.
3. Prefer pause_reminder over cancel_reminder. Cancel permanently deletes the reminder and its delivery history with no undo; use it only when the user explicitly says delete or stop permanently.
4. The chain is the user's choice: one step or up to five, any channel (email, whatsapp, sms, call) in any order with any gaps. Build what the user asked for and do not add channels or steps they did not ask for; calls and SMS cost far more than email and WhatsApp.
5. Send times in the user's own words as 'YYYY-MM-DDTHH:mm'; it is read in the account's timezone. Do not send a timezone field; the account's timezone always wins.
6. Pass a stable idempotency_key on create if you might retry, so a retry returns the original reminder instead of making a second phone call.
7. Do not quote per-channel credit prices from memory; they vary by destination country. Call get_account for the balance and point the user to https://nudgebell.app/pricing for prices.
8. A create is refused (insufficient_credits, 402) when the balance cannot cover the first step. Nothing is created in that case; tell the user to top up at https://nudgebell.app/settings.

## Docs

- [Full agent reference, plain text](https://nudgebell.app/llms-full.txt): everything below in one file; tools, REST endpoints, examples, recurrence, idempotency, limits, credits, every error code.
- [Agent API and MCP Server](https://nudgebell.app/docs): the same reference as HTML. The anchors that follow are sections of that one page.
- [MCP setup](https://nudgebell.app/docs#mcp): Claude Code, .mcp.json and Cursor config blocks.
- [REST endpoints](https://nudgebell.app/docs#rest): POST and GET /api/v1/reminders, /{id}, /{id}/status, /{id}/pause, /{id}/cancel, GET /api/v1/account.
- [Error codes](https://nudgebell.app/docs#errors): machine-readable code, message and docs_url on every failure.
- [Limits](https://nudgebell.app/docs#limits): rate limits per key, active-reminder limits per plan, 5-year scheduling horizon.

## Product

- [Home](https://nudgebell.app/): how escalation works, use cases for agents and for people, pricing summary, FAQ.
- [Pricing](https://nudgebell.app/pricing): Starter $5/month (250 credits, 5 active reminders), Pro $15/month (1,200 credits, 15 active), Power $49/month (4,500 credits, unlimited). Yearly is 20% off. Top-up packs from $5. Credits roll over.
- [Refund policy](https://nudgebell.app/refund)
- [Privacy](https://nudgebell.app/privacy)
- [Terms](https://nudgebell.app/terms)

## Optional

- [Blog](https://nudgebell.app/blog)
- [Reminder app that calls you](https://nudgebell.app/reminder-app-that-calls-you)
- [WhatsApp reminder app](https://nudgebell.app/whatsapp-reminder-app)
- [Subscription renewal reminder](https://nudgebell.app/subscription-renewal-reminder)