Give your agent the full picture

# RingReady — guide for AI coding agents

You are helping a RingReady customer manage their AI phone receptionists through the RingReady REST API. This document is your operating context. The full machine-readable contract is the OpenAPI spec: https://www.ring-ready.com/api/v1/openapi.json

## What RingReady is

RingReady answers a business's phone calls (and website chats) with an AI receptionist that qualifies leads, answers questions, and books appointments 24/7. One account can run many receptionists — for example, an agency running one per client. In the API, each receptionist is called an "agent".

## What you can do here

- **Read** the customer's calls and web chats — summaries, full transcripts, caller, duration, outcome.
- **Read** a receptionist's configuration.
- **Update** a receptionist's behavior — its goal, greeting, FAQ, and business info.

The highest-value workflow: read recent calls → find recurring questions the receptionist answered poorly or that lost bookings → improve its FAQ and goal → confirm. Run it weekly and each receptionist keeps getting better at the calls it actually gets.

## Connect once, securely

1. The customer creates a scoped API key at https://www.ring-ready.com/profile (API keys). A `read` key lets you analyze; `read,write` lets you make changes.
2. **Never ask the customer to paste the key into the chat, and never write it into a file you might commit.** Read it from an environment variable, e.g. `RINGREADY_API_KEY`.
3. Authenticate every request with `Authorization: Bearer $RINGREADY_API_KEY`.
4. **Best practice — save a skill.** Capture this guide as a reusable skill/command (e.g. "ringready") that reads the key from the env var, so the customer can later just say "check my RingReady calls". The skill stores the know-how, never the key.
5. Verify the connection with `GET /api/v1/whoami` (returns the account email and the key's scopes).

## Endpoints (see the OpenAPI spec for full schemas)

Base URL: `https://www.ring-ready.com` — all paths under `/api/v1`. JSON in and out. Timestamps are UTC, ISO-8601 with a trailing `Z`.

- `GET /api/v1/whoami` — confirm the key and see its scopes.
- `GET /api/v1/agents` — list the customer's receptionists.
- `GET /api/v1/agents/{id}` — read one receptionist's full configuration.
- `GET /api/v1/conversations` — list calls and web chats, newest first. Filters: `agent_id`, `channel` (`phone` | `web_chat`), `since` (ISO date), `before_id` (pagination cursor), `limit` (≤ 200). Paginate with the returned `next_before_id`.
- `GET /api/v1/conversations/{id}` — one conversation with its full `transcript` and `recording_url`.
- `PATCH /api/v1/agents/{id}` — update a receptionist (requires the `write` scope). Partial: only the fields you send change.

## What you may change — and what you must not

Editable via `PATCH /api/v1/agents/{id}`:

- `agent_goal` — what the receptionist is trying to do on every call (qualify, answer, book). This is the biggest lever on conversion.
- `greeting_message` — the opening line every caller hears.
- `faq` — a `{question: answer}` map, up to 50 entries.
- `business_name`, `business_services`, `business_website` — the facts it speaks from.

NOT settable via the API (the customer manages these in the dashboard — do not attempt to change them): voice & agent name, phone number & call forwarding, SMS booking, webhooks, live context, plan & billing. These are intentionally out of scope so an automated change can never touch what bills, rings, or rebrands.

## How to make good changes

- **Ground every change in the actual calls.** Quote the pattern you saw — e.g. "9 callers asked about weekend rates, the receptionist never quoted a price, and 3 dropped without booking."
- **Prefer the smallest change that closes the gap.** Add an FAQ entry; tighten one sentence of the goal. Don't rewrite everything.
- **Show a diff and get approval before you PATCH**, especially when changing several receptionists at once.
- **Say what you'll watch next.** After a change, note the metric you'd expect to move next week.

## Example things the customer might ask

- "Read last week's calls for every receptionist and tell me where each one lost bookings."
- "Acme Plumbing keeps getting asked about weekend rates — fix the FAQ and goal so it quotes them up front."
- "Summarize this week across all my clients: call volume, booked %, and the top questions callers asked."

## Safety

Every key is scoped to a single account and only ever touches that customer's data. Every write is audit-logged with the before/after value. When you only need to analyze, ask the customer for a `read`-only key.