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, web chats, and inbound SMS — summaries, full transcripts, caller, callback number, duration, outcome.
- **Read** a receptionist's full configuration, including which plan features are configured vs. actually active (`entitlements`).
- **Update** a receptionist's behavior — its goal, greeting, FAQ, business facts (name, services, website, address, service areas, hours, timezone), and voice.
- **Configure** integrations — webhooks, ad-platform conversions (Meta / Google / TikTok CAPI), call recording, and where email notifications go.

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, plan, and `entitlements`.
- `GET /api/v1/voices` — the voice catalog (keys for `PATCH {"voice": ...}`; each voice carries the receptionist's spoken name).
- `GET /api/v1/conversations` — list calls, web chats, and inbound SMS, newest first. Filters: `agent_id`, `channel` (`phone` | `web_chat` | `sms`), `since` (ISO date), `before_id` (pagination cursor), `limit` (≤ 200). Paginate with the returned `next_before_id`. Rows include `callback_number` when one was captured.
- `GET /api/v1/conversations/{id}` — one conversation with its full `transcript`, `recording_url`, caller address, and owner comments.
- `PATCH /api/v1/agents/{id}` — update a receptionist (requires the `write` scope). Partial: only the fields you send change.

## Configured vs. active — read `entitlements` before promising anything

Some features are included only on higher plans (Growth / Scale). The API lets you **configure them on any plan** — the config saves, but the feature only runs once the plan includes it. `GET /agents/{id}` returns an `entitlements` block per feature: `{configured, plan_includes, active, required_tier}`, and every PATCH that touches a gated feature echoes an `activation` block. **`active` is the truth about runtime behavior.** If you configure something and `active` is false, tell the customer plainly: "it's set up and will go live when you upgrade to <required_tier>" — never imply it's already working.

## Goal modes — check `goal_source` before editing the goal

A receptionist's objective comes from ONE of two sources: `goal_source: "prompt"` (the free-text `agent_goal`) or `goal_source: "list"` (a structured collect-list, shown read-only as `agent_goal_list`). In list mode the free-text goal is inactive, and `PATCH agent_goal` returns **409** instead of silently doing nothing. `goal_source` is itself writable: PATCH `{"goal_source": "prompt", "agent_goal": "..."}` switches a list-mode agent to prompt mode and sets the goal in one request (get the customer's approval first — it changes how the receptionist behaves). Switching TO `"list"` requires a collect-list already built in the dashboard; the list's content is not editable via the API.

## 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). The biggest lever on conversion. Check `goal_source` first (see above).
- `goal_source` — `"prompt"` or `"list"`; switches which goal drives the agent (list mode needs a dashboard-built collect-list).
- `greeting_message` — the opening line every caller hears.
- `faq` — a `{question: answer}` map, up to 50 entries.
- `business_name`, `business_services`, `business_website`, `business_address`, `business_service_areas` — the facts it speaks from.
- `business_hours` — per-day ranges, e.g. `{"mon": [{"open": "08:00", "close": "17:00"}]}` (null clears). `timezone` — IANA name.
- `voice` — a key from `GET /voices`. **This renames the receptionist** (the spoken name derives from the voice; the response returns the new `agent_name`). If the greeting mentions the old name, update `greeting_message` in the same PATCH.
- `agent_notification_email` — where call summaries are emailed (empty = the account's login email). Changing it triggers a security notice to the account owner.
- `webhook_enabled`, `webhook_url` — POST call summaries to the customer's endpoint. Enabling requires a URL.
- `recording_enabled` — call recording (Growth+; callers hear a consent notice when active).
- `capi` — ad-platform conversions, per channel: `{"google": {"enabled": true, "pixel": {...}, "events": [...]}}` (Scale). Channels you omit are untouched. Tokens/secrets are **write-only**: send them to set them; reads only return `has_access_token` / `has_api_secret`. Sending a pixel without its token keeps the stored one.

NOT settable via the API (the customer manages these in the dashboard — do not attempt to change them): the structured goal list, phone number & call forwarding, the SMS notification number (verify-first, dashboard-only; reads are masked), SMS booking, web chat, live context, plan & billing. An automated change can never touch what bills or rings.

## 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 (secrets masked). Changes that re-route notifications (`agent_notification_email`, webhooks) additionally email a security notice to the account owner. When you only need to analyze, ask the customer for a `read`-only key.