RingTonic MCP server

List every workspace this key can reach, with the caller's role and whether the workspace's plan currently enables the API/MCP surface. Call this first when unsure which workspace to pass to other tools. The uuid is the stable, canonical identifier to use.

Read one workspace's profile — name, timezone, currency, consent defaults, and the custom-field schema you need before writing custom_fields on contacts.

List a workspace's campaigns as compact rows (uuid, name, tracking type, routing status, attached call flow). Cursor-paginated. Use get_campaign for a campaign's full detail.

Read one campaign's full detail by uuid — tracking config, routing flags, timezone override, and the attached call flow.

Create a campaign. tracking_type is "static" (forward a number) or "dni" (website/dynamic-number tracker). Optionally link existing unassigned tracking numbers by uuid. Pass idempotency_key and reuse it on retry so a retry does not create a second campaign.

Update one campaign by uuid (partial — omit a field to leave it unchanged). Also attaches or detaches its call flow: pass call_flow as a flow uuid to attach, or null to detach. Pass idempotency_key and reuse it on retry.

Delete one campaign by uuid. Requires number_action: "unassign" returns its tracking numbers to your inventory, "release" permanently gives them back to the provider (which additionally needs the numbers:provision scope).

List a workspace's calls as compact rows (uuid, direction, status, timing, caller, lead status, campaign, tracking number, contact). Cursor-paginated. Use get_call for a call's full detail, transcript, and recording.

Read one call's full detail by uuid — timing, caller, lead status, keyword spots, attribution, and signed recording/voicemail URLs. Pass include_transcript to also return the transcript.

Update one call by uuid: its lead_status (qualification), deal_value (minor units of the workspace currency, e.g. cents), and tags (replaces the whole set — each entry is an existing tag uuid or exact name; [] or null clears them). Omit a field to leave it unchanged.

Permanently delete one call log by uuid. This cannot be undone: the recording, transcript, and daily metrics are removed and the contact's call counts are corrected.

List a workspace's contacts as compact rows (uuid, name, phone, email, company, lead status, source). Cursor-paginated. Use match_contact to resolve identifiers, or get_contact for full detail.

Diagnose which contact a set of identifiers (external_id, phone, email) resolves to, without writing anything. Reports matched / ambiguous / conflicting / no-match with public uuids, so you can pick the right target before an upsert.

Read one contact's full detail by uuid — identifiers, stage, deal value, custom fields, tags. Pass include_events to also embed the conversion-event timeline (cursor-paginated under events).

Create or update a contact. Without contact: identify-or-create by external_id/phone/email (a match on phone/email returns the contact unchanged; use contact to update it). With contact (a uuid from match_contact/search_contacts): update that contact — the identifiers become new values, and lead_status/deal_value/force_stage are accepted only here. Send idempotency_key and reuse it on retry.

Delete one contact by uuid. This is a soft delete: the contact stops appearing in searches, its tags are detached, but its call history is preserved and a later postback with the same identifier restores it.

List a workspace's conversion events (stage change, source, value, linked contact/call/form) as full rows. Cursor-paginated.

Record a conversion that moves a contact to a funnel stage and writes an auditable event. Identify the contact by contact uuid or by external_id/phone/email; create_if_missing creates one when nothing matches. won/proposal_sent stages need value_cents (or inherit_value). Send idempotency_key and reuse it on retry.

List a workspace's tracking numbers (phone number, friendly name, assigned campaign, call-control flags). Cursor-paginated.

Read one tracking number's full detail by uuid — phone number, friendly name, assigned campaign, provider, CNAM, call-control flags, and ad location.

Update one tracking number by uuid: friendly_name, campaign_uuid (assign, or null to unassign — re-points the number at the provider), cnam_lookup_enabled, calls_enabled + calls_disabled_action/message (Agency plan), and ad_location. Omit a field to leave it unchanged.

Search the telephony provider for numbers you could buy in a country. Provider-agnostic. Not paginated (one bounded page); narrow with number_type, area_code, contains, or capabilities. Nothing is reserved — a listed number can be sold before you buy it, so on a purchase failure, search again.

Buy a tracking number. THIS SPENDS MONEY — always send idempotency_key and reuse it on retry, or a timeout-retry buys a second number. Name an exact phone_number from search_available_numbers, OR give search criteria (country, number_type, area_code, contains, capabilities) to auto-pick the first match — not both. Optionally assign a campaign_uuid and a friendly_name. Subject to the workspace daily purchase cap (shared with the REST API).

Release one tracking number by uuid back to the telephony provider. NOT REVERSIBLE: the number leaves your account, stops taking calls immediately, and can be bought by someone else. Call history is kept (soft delete). To take a number out of service without giving it up, unassign it instead (update_tracking_number with campaign_uuid: null).

List a workspace's call flows (name, description, publish status, live version, attached-campaign count). Cursor-paginated. Use get_call_flow for a flow's versions and graph.

Read one call flow's full detail by uuid — status, live version, attached campaigns, and (cursor-paginated under versions) its publish history. Pass include_graph to also return the draft and/or published node/edge graph.

Create a call flow. It starts as a draft (no live version) and answers no calls until you publish it. graph is optional — omit it for a blank flow, or send a node/edge graph (Go-To targets are call-flow uuids). A graph is validated at publish strictness now, so an invalid one is rejected at create time. Pass idempotency_key and reuse it on retry so a retry does not create a second flow.

Replace a call flow's DRAFT graph wholesale (the published version and live routing are untouched until you publish). Read the current graph with get_call_flow (include_graph: draft) first, then send the full nodes/edges graph back. Go-To targets are call-flow uuids. To keep a webhook credential, echo it back as its masked value ******** — it is restored only while the webhook's url and method are unchanged. The graph is validated at publish strictness: invalid graphs return per-node validation errors. A concurrent change to the draft returns a conflict — re-read and re-apply.

Publish a call flow's draft as a new live version. THIS CHANGES CALL ROUTING: every campaign using this flow starts answering with the new version. A flow with generated audio returns status "publishing" and becomes active (or failed) shortly — poll get_call_flow. A busy flow (a concurrent or still-generating publish) returns a conflict; a draft that cannot go live (invalid graph, a node type your plan lacks, or a required test call) returns a validation-error. Pass idempotency_key and reuse it on retry so a retry does not publish twice.

Restore a past version's graph into the call flow's DRAFT (by version_number, from get_call_flow's versions history). This activates nothing — call publish_call_flow afterwards to put the restored graph live. Pass idempotency_key and reuse it on retry.

Duplicate a call flow by uuid. The copy is a new draft (name suffixed " (Copy)") with no published version — it answers no calls until you publish it. Pass idempotency_key and reuse it on retry so a retry does not create a second copy.

Delete one call flow by uuid. THIS CHANGES CALL ROUTING: every campaign using this flow is detached (call_flow_id nulled) and falls back to its non-flow routing, and its tracking numbers are re-synced at the provider. The flow is soft-deleted. There is no undo through this API.

List a workspace's appointments (status, start/end time, title, linked contact and call). Cursor-paginated.

Read one appointment's full detail by uuid — status, timing, title, notes, location, calendar event id, linked contact and call, and cancellation info.

Book an appointment. Identify the customer with contact (a uuid from match_contact/search_contacts) OR an inline new_contact (a phone is required; needs the contacts:write scope). start_at is an ISO-8601 instant WITH an offset or Z; duration_minutes is 5-480. Confirmations and reminders are opt-in. A slot overlap returns a conflict — to book anyway resend with ignore_conflicts under a NEW idempotency_key. Send idempotency_key and reuse it on retry.

Reschedule or edit a booked appointment (identified by its uuid). Send only the fields to change: start_at and/or duration_minutes to move it, or title/notes/location to edit details — at least one is required. Only booked appointments can be edited. A slot overlap returns a conflict; resend with ignore_conflicts to override. Not idempotent — a repeat re-syncs the calendar and re-notifies, so do not blind-retry.

Set an appointment's status by uuid: cancelled (removes the calendar event, optionally notifies the customer via notify_customer, records reason), completed, no_show, or booked (re-open a terminal appointment). reason, notify_customer and idempotency_key apply only when cancelling; send idempotency_key on a cancellation and reuse it on retry so the retry replays instead of cancelling twice.

List a workspace's captured form submissions (campaign, fields, marketing params, consent, spam flag). Cursor-paginated. Pass uuid to return one submission's full payload instead (cannot be combined with filters, sort, cursor, or per_page).

List a workspace's contact tags (name, color). Cursor-paginated, alphabetical by default.

Create, update, or delete a workspace contact tag. action: "create" (name required, optional hex color; pass idempotency_key and reuse it on retry so a retry does not create a second tag), "update" (tag uuid + the fields to change), or "delete" (tag uuid). Tag names are unique per workspace.

List a workspace's product/service catalog (name, description, category, price range, active flag). Cursor-paginated, alphabetical by default.

Create, update, or delete a product/service in the workspace catalog. action: "create" (name required; optional description, category, price_min/price_max in integer cents, is_active; pass idempotency_key and reuse it on retry so a retry does not create a second entry), "update" (product uuid + the fields to change; omit a field to leave it unchanged, send null to clear a nullable one), or "delete" (product uuid).

List a workspace's effective blocked numbers, including account-inherited entries (flagged scope "account", read_only true). Cursor-paginated.

Block or unblock a phone number for the workspace. action: "block" (phone_number + reason; optional note; pass idempotency_key and reuse it on retry) or "unblock" (blocked_number uuid). Only the workspace's own entries can be unblocked — account-inherited entries (scope "account") are read-only.

List a workspace's webhook endpoints (url, subscribed events, active flag, health). Cursor-paginated. Use get_webhook_endpoint for a single endpoint's delivery statistics.

Read one webhook endpoint's full detail by uuid — url, subscribed events, health, and 24-hour delivery statistics (count, success rate, average response time).

Manage webhook endpoints. action: "create" (name, https url, events[]; returns the signing secret ONCE — it enters this conversation; pass idempotency_key and reuse it on retry), "update" (webhook_endpoint uuid + fields; setting is_active true re-enables and resets the failure circuit breaker), "delete" (webhook_endpoint uuid), "test" (webhook_endpoint uuid + event_type the endpoint subscribes to — queues a sample delivery; idempotency_key replays instead of sending twice), or "regenerate_secret" (webhook_endpoint uuid — rotates and returns a NEW secret ONCE; ALWAYS pass idempotency_key and reuse it on retry, or a blind retry rotates twice and strands the first value).

Call totals, a day/week/month time series, and status/direction/lead_status breakdowns over a date range, optionally for one campaign. Totals and the time series are inbound marketing analytics (matching the dashboard); the breakdowns count every call in the window across both directions. Dates are YYYY-MM-DD in the workspace (or scoped campaign) timezone.

Attribution totals and top source, per-source performance rows (calls, qualified, conversion rate, cost, revenue, ROI), and a per-source-and-medium breakdown over a date range, optionally for one campaign. Dates are YYYY-MM-DD in the workspace timezone.

The lifecycle stage funnel (per-stage counts, exits, and percent-from-previous) plus per-source-and-medium revenue rows (leads, qualified, won, revenue) over a date range, optionally for one campaign. Dates are YYYY-MM-DD in the workspace timezone.

Per-tracking-number call volume, answered/missed/failed/spam counts, missed rate, and average duration over a date range, optionally for one campaign. Dates are YYYY-MM-DD in the workspace timezone.