# Eppie Agent

> Phone numbers and voice agents for AI agents. Sign your user up, top up a prepaid wallet, create a voice agent (OpenAI gpt-live-1), buy a US number, and read call transcripts — no human steps required.

## Connect

- MCP (OAuth, recommended for Claude, ChatGPT, Cursor…): https://agent.eppie.ai/mcp
- REST: https://agent.eppie.ai/v1 — OpenAPI at https://agent.eppie.ai/openapi.json — send `Authorization: Bearer eppie_agent_sk_…`, or an OAuth access token from https://agent.eppie.ai/.well-known/oauth-authorization-server (the same token works on MCP and REST)

## REST quickstart

1. `POST /v1/auth/email-code` with `{"email": "<your user's email>"}`. A 6-digit code is emailed. Read it from the inbox if you can, or ask your user.
2. `POST /v1/auth/verify` with `{"email": "...", "code": "123456"}` → `{"api_key": "eppie_agent_sk_..."}`. Shown once; store it. The same two calls log in to an existing account.
3. `POST /v1/wallet/topups` with `{"amount_usd": 20, "shared_payment_token": "spt_..."}` (a Stripe shared payment token from your wallet, e.g. Link) — credited immediately (send an `Idempotency-Key` header to retry safely). Without a token you get a `checkout_url`; once it's paid, `GET /v1/wallet/topups/{id}` shows `succeeded`. Amounts: $10–$500.
4. `GET /v1/voices`, then `POST /v1/agents` with `{"name": "Front desk", "instructions": "...", "opener": "How can I help?"}`. Instructions and opener can use {{caller_number}} (the other party), {{local_time}}, {{agent_name}} and {{direction}} (inbound or outbound); batch targets can add their own variables.
5. `GET /v1/numbers/available?area_code=415`, then `POST /v1/numbers` with `{"e164": "+1415...", "agent_id": "<agent id>"}` (send an `Idempotency-Key` header to retry safely).
6. People who call the number talk to the agent. Read results with `GET /v1/calls` and `GET /v1/calls/{id}` (status, end_reason, reject_reason, duration_s, cost_usd, transcript).

## Outbound calls

1. Have a voice agent and a number (steps 4–5).
2. `POST /v1/batches` with `{"agent_id": "...", "targets": [{"to": "+1...", "variables": {"first_name": "Dana"}}], "consent": {"source": "how these people agreed to be called"}}`. Up to 1,000 targets; `variables` fill {{name}}-style fields in the agent's instructions. Optional: `context` (a note for this batch), `opener` (said right after the disclosure), `outcome_schema` (a JSON Schema; each answered call gets an `outcome`), `webhook_url`, `from`. One number: `POST /v1/calls` with `to` instead of `targets`. Send an `Idempotency-Key` header to retry safely.
3. Follow it with `GET /v1/batches/{id}` (counts by status) and `GET /v1/calls?batch_id=...` (status, answered_by, transcript, outcome). `POST /v1/batches/{id}/pause`, `/resume` and `/cancel` control it.
4. Webhooks (optional): `call.finished` and `batch.completed` POSTs, signed `x-eppie-signature: t={unix},v1={hex HMAC-SHA256(secret, t + "." + body)}` with the secret from `GET /v1/webhook-secret`.
5. To retry people who didn't answer, send their numbers (`status=no_answer`) as a new batch.

## Calling rules

- Only call people who agreed to be called, and say how in `consent.source`. Accounts that draw complaints are suspended.
- Calls go out 08:00–21:00 in the recipient's time zone. Numbers on your do-not-call list (`POST /v1/do-not-call`) are skipped, and anyone who asks not to be called again is added automatically.
- Answering machines are hung up on (no voicemail messages). People who call back within 7 days reach the same agent, which knows about the earlier call.

## Prices

- Calls: $0.12 per minute, billed per second, inbound and outbound. Outbound calls are only charged when a person answers. A call is only answered or dialed with at least $0.50 of spare balance and is capped at what the balance covers; a batch pauses itself when the money runs out and resumes after a top-up.
- Numbers: $3.00 per month, charged at purchase and monthly. If a renewal can't be paid the number stays live for 7 days, then is released.

## Limits

- New accounts: 2 numbers, 2 concurrent calls (inbound and outbound together), 200 outbound calls per 24 hours, $100.00 of top-ups per 24 hours.
- After $100.00 of lifetime top-ups: 10 numbers, 10 concurrent calls, 2,000 outbound calls per 24 hours, $1000.00 per 24 hours.
- 120 requests per minute per credential.

## Rules every call follows

- Callers first hear: "Hi, you've reached an AI assistant for <agent name>. This call is transcribed." People we call first hear: "Hi, this is an AI assistant calling on behalf of <agent name>. This call is transcribed."
- Agents never claim to be human. Calls are transcribed, never recorded as audio.

## Errors

Every error is `{"error": {"code", "message", "field", "next_step"}}`. `next_step` says what to do.