# AgentRing (agentring.dev) — Complete Technical & Platform Specification (llms-full.txt)

> Comprehensive, token-efficient, machine-readable documentation of AgentRing's features, voice architecture, API endpoints, webhook schemas, pricing, and FAQ for advanced AI agents, search engines, and indexers.

---

## 1. Executive Summary & Brand Identity

- **Platform Name:** AgentRing
- **Domain:** `https://agentring.dev`
- **Core Product:** Multi-Tenant, 24/7 AI-Powered Conversational Phone Answering Service for Home Services & Trades (Plumbers, HVAC, Electricians, Roofers, Landscaping, General Contractors, Small Business).
- **Core Value Proposition:** Replaces traditional voicemail and expensive $400+/mo human answering services (e.g., Ruby, Smith.ai) with an instant-response, conversational AI agent that answers inbound phone calls in <800ms, qualifies leads, schedules appointments directly into Google Calendar and Calendly, and live-transfers emergency callers with private AI whisper briefings.

---

## 2. Telephony & Audio Pipeline Architecture

AgentRing does not use slow, concatenated Text-to-Speech (TTS) / Speech-to-Text (STT) cascades. Instead, it utilizes native Speech-to-Speech audio streaming with Google Gemini Live:

```
Caller (PSTN)
   │
   ▼
Twilio Voice Gateway (SIP / TwiML Media Streams)
   │  • Format: 8,000 Hz, 8-bit µ-law, Base64 JSON over WebSockets
   ▼
AgentRing Voice Bridge (FastAPI / voice_bridge.py / api/stream.py)
   │  • Inbound: µ-law decode ➔ Linear PCM16 ➔ Resample 8kHz ➔ 16kHz
   ▼
Google Gemini Live API (`gemini-3.8-live` via google-genai)
   │  • Low-latency bidirectional session
   │  • Audio In: 16,000 Hz, 16-bit PCM Mono
   │  • Audio Out: 24,000 Hz, 16-bit PCM Mono
   ▼
AgentRing Voice Bridge (Outbound Worker)
   │  • Outbound: Resample 24kHz ➔ 8kHz ➔ PCM16 to µ-law encode ➔ Base64
   ▼
Twilio Media Streams
   │
   ▼
Caller Ear (<800ms total round-trip speech latency)
```

### True Natural Barge-In (Interruption Handling)
- When Twilio detects incoming caller speech or emits a `clear` media event, AgentRing's `AudioStreamer` immediately flushes the outbound audio buffer, halts active transmission to Twilio, and cancels the in-flight Gemini generation.
- Result: Callers can interrupt the receptionist mid-sentence naturally without audio stuttering or clipping.

---

## 3. Verified Core Features Matrix

### 3.1 24/7 Call Answering & Local Phone Numbers
- Instant provisioning of dedicated local 10-digit US phone numbers across all US area codes.
- Supports carrier call forwarding (conditional forwarding `*71` / `*67` or unconditional `*72`) from existing business numbers (AT&T, Verizon, T-Mobile, VoIP).
- High-concurrency architecture supporting up to 50 simultaneous incoming calls per tenant without busy signals.

### 3.2 Two-Way Google Calendar Scheduling
- Connects directly to Google Calendar via OAuth2 (`/api/calendar/initiate`).
- Direct availability check tool (`check_availability`): Reads existing busy blocks, tenant business hours, and buffer times.
- Real-time booking tool (`book_appointment`): Writes client name, phone, address, and service notes directly to the business calendar.
- Timezone-aware: Automatically converts caller requests to the business's operational timezone.

### 3.3 Two-Way Calendly Scheduling with Webhook Sync
- Connects to Calendly via OAuth 2.0 PKCE (`/api/calendly/initiate`).
- Transparent single-use refresh token rotation with Fernet symmetric encryption at rest.
- Bookable 1-on-1 event type discovery (`/api/calendly/event-types`) and active calendar selection (`/api/calendly/event-type`).
- Live voice availability check tool queries real-time openings via Calendly API (`/event_type_available_times`).
- Real-time voice booking tool directly creates invitees (`POST /v2/invitees`) with automatic deterministic caller email synthesis (`booking-{tenant_id}-{phone_tail}@agentring.dev`) when callers do not spell out email verbally.
- Inbound webhook synchronization (`api/calendly_webhook.py`) with HMAC-SHA256 signature verification and 300s replay protection for `invitee.created` and `invitee.canceled`.
- Note: Direct programmatic invitee booking via API requires a Calendly Standard or higher tier.

### 3.4 Live Emergency Call Transfer with AI Whisper Briefings (Growth & Scale Plans)
- When a caller reports an urgent issue (e.g., "pipe burst", "no heat in freezing temps", "electrical spark"), AgentRing triggers an automated bridge.
- The AI calls the contractor's emergency phone number.
- When the contractor answers, the AI whispers a private briefing: *"Emergency call from John regarding a flooded basement on Oak Street. Press 1 to connect."*
- If the contractor doesn't answer within 20 seconds, the AI gracefully resumes the caller and records a priority voicemail summary.

### 3.5 Custom Dynamic Procedures & Extraction Fields
- **Step-by-Step Procedure Engine:** Contractors specify ordered instructions:
  - Step 1: Default Greeting & business introduction
  - Step 2: Emergency detection & triage
  - Step 3: Information collection (address, issue description)
  - Step 4: Appointment booking or live transfer
  - Step 5: Goodbye message
- **Dynamic Field Extraction:** Automatically extracts structured data (`name`, `date`, `time`, `street`, `city`, `issue`, `custom_field`).
- Pushes leads and transcripts directly to the Next.js Dashboard and optional webhook/Google Sheets.

### 3.6 Native 1-Click HubSpot CRM Integration
- Direct OAuth 2.0 integration via `/api/hubspot/initiate` and `/callback`.
- Automatic contact deduplication: searches existing contacts by phone number (`/crm/v3/objects/contacts/search`).
- Contact synchronization: creates new contacts or updates existing records with caller name and extracted address/lead properties.
- Call activity logging: logs a HubSpot Call Engagement (`/crm/v3/objects/calls`) linked to the contact with call duration, summary, and audio recording link.

### 3.7 Role-Based Access Control (RBAC) & Team Management
- Multi-user tenant workspaces (Owner, Admin, Viewer).
- **Admin:** Full privileges (prompt configuration, number provisioning, billing management, team invites).
- **Viewer:** Read-only access to call logs, transcripts, calendar, and AI configuration without modification rights.
- Real-time role synchronization without session caching traps.

### 3.8 Call Recordings & Dual-Channel Diarized Transcripts
- Secure audio recording storage with in-dashboard waveform playback.
- Diarized transcripts separating caller utterances from AI receptionist responses with exact timestamps.
- Automated AI bullet summaries for quick triage.

### 3.9 Real-Time Multilingual Voice Support (Google Gemini 3.8 Live — Up to 97 Languages)
- **Zero-Latency Real-Time Detection**: Powered by Google Gemini 3.8 Live native speech-to-speech architecture, AgentRing answers with sub-800ms natural latency, automatically detecting the caller's spoken language on the fly and responding fluently without requiring phone menu navigation or keypresses.
- **Deep Trade & Field Jargon**: Specifically trained on contracting terminology across residential and commercial trades (e.g., in Spanish: *fuga de gas*, *tubería rota*, *calentador de agua*, *tablero eléctrico*, *aire acondicionado*, *bajante pluvial*, *termostato*; in French, Polish, Portuguese, Vietnamese, Tagalog, etc.).
- **Complete Alphabetical Directory of All 97 Supported Languages**:
  1. Afrikaans
  2. Albanian
  3. Amharic
  4. Arabic (Modern Standard, Egyptian, Levantine, Gulf)
  5. Armenian
  6. Assamese
  7. Azerbaijani
  8. Basque
  9. Belarusian
  10. Bengali
  11. Bhojpuri
  12. Bosnian
  13. Bulgarian
  14. Burmese (Myanmar)
  15. Catalan
  16. Cebuano
  17. Chinese (Mandarin - Simplified)
  18. Chinese (Mandarin - Traditional)
  19. Chinese (Cantonese - Hong Kong)
  20. Corsican
  21. Croatian
  22. Czech
  23. Danish
  24. Dutch (Netherlands & Flemish)
  25. English (US, UK, Canadian, Australian, Indian, New Zealand, South African)
  26. Esperanto
  27. Estonian
  28. Farsi (Persian)
  29. Filipino (Tagalog)
  30. Finnish
  31. French (Canadian, European, African)
  32. Galician
  33. Georgian
  34. German (Germany, Austria, Switzerland)
  35. Greek
  36. Gujarati
  37. Haitian Creole
  38. Hausa
  39. Hawaiian
  40. Hebrew
  41. Hindi
  42. Hmong
  43. Hungarian
  44. Icelandic
  45. Igbo
  46. Indonesian
  47. Irish
  48. Italian
  49. Japanese
  50. Javanese
  51. Kannada
  52. Kazakh
  53. Khmer
  54. Kinyarwanda
  55. Korean
  56. Kurdish (Kurmanji & Sorani)
  57. Kyrgyz
  58. Lao
  59. Latin
  60. Latvian
  61. Lithuanian
  62. Luxembourgish
  63. Macedonian
  64. Malagasy
  65. Malay
  66. Malayalam
  67. Maltese
  68. Maori
  69. Marathi
  70. Mongolian
  71. Nepali
  72. Norwegian (Bokmål & Nynorsk)
  73. Odia (Oriya)
  74. Pashto
  75. Polish
  76. Portuguese (Brazilian & European)
  77. Punjabi (Gurmukhi & Shahmukhi)
  78. Romanian
  79. Russian
  80. Samoan
  81. Scots Gaelic
  82. Serbian
  83. Sesotho
  84. Shona
  85. Sindhi
  86. Sinhala (Sinhalese)
  87. Slovak
  88. Slovenian
  89. Somali
  90. Spanish (Mexican, US Latino, Latin American, Castilian)
  91. Sundanese
  92. Swahili
  93. Swedish
  94. Tajik
  95. Tamil
  96. Telugu
  97. Vietnamese
  *(Also supporting regional languages: Turkish, Ukrainian, Urdu, Uzbek, Welsh, Yiddish, Yoruba, and Zulu)*
- **Configurable Language Operational Modes**:
  - **Global Polyglot Auto (Up to 97 Languages)**: Recommended mode. Real-time automatic caller language detection and seamless conversational switching.
  - **Bilingual English + Spanish**: Tailored specifically for US trade contractors, crew foremen, subcontractors, and Spanish-speaking homeowners.
  - **Dedicated Primary Language**: Configure a dedicated primary non-English greeting and conversation flow.
  - **English-Only Mode**: Constrains conversational output strictly to English.

---

## 4. Plans & Pricing Structure

| Plan Tier | Price | Monthly Minutes | Overage Rate | Included Features |
| :--- | :---: | :---: | :---: | :--- |
| **Starter** | $49 / month | 300 minutes (~60–80 calls) | $0.40 / min | Dedicated US number, 24/7 answering, Google Calendar & Calendly booking, lead extraction, email alerts. |
| **Growth** | $99 / month | 1,000 minutes (~200–250 calls) | $0.40 / min | All Starter features + Live Whisper Call Transfer, 3 Team Member Seats (Admin/Viewer), priority routing. |
| **Scale** | $199 / month | 2,500 minutes (~500–625 calls) | $0.40 / min | All Growth features + High-concurrency capacity, custom extraction webhooks, dedicated account onboarding. |

*Billing is handled via Stripe Customer Portal. Minute allowances refresh monthly. No annual lock-in; cancel anytime.*

---

## 5. REST API & Webhook Specifications

### 5.1 Authentication
- Endpoints require Bearer JWT token header (`Authorization: Bearer <token>`) and tenant header (`X-Tenant-ID: <id>`).

### 5.2 Core Endpoints
| HTTP Method | Path | Description | Access |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/auth/register-tenant` | Registers new tenant account & default configuration | Public |
| `POST` | `/api/auth/jwt/login` | Authenticates user and returns JWT token | Public |
| `GET` | `/api/auth/users/me` | Fetches active user details and live RBAC role | Authenticated |
| `GET` | `/api/tenant/profile` | Retrieves business profile, hours, and extraction schema | Authenticated |
| `POST` | `/api/tenant/profile` | Updates business profile, greeting, and procedure | Admin Only |
| `POST` | `/api/tenant/provision-number` | Provisions a new local phone number | Admin Only |
| `GET` | `/api/tenant/records` | Returns recent call logs, recordings, and transcripts | Authenticated |
| `GET` | `/api/appointments` | Lists scheduled appointments with calendar sync status | Authenticated |
| `POST` | `/api/appointments` | Manually creates a new appointment | Admin Only |
| `PATCH` | `/api/appointments/{id}` | Updates or reschedules an appointment | Admin Only |
| `DELETE` | `/api/appointments/{id}` | Cancels an existing appointment | Admin Only |
| `GET` | `/api/calendar/status` | Checks Google Calendar OAuth connection status | Authenticated |
| `GET` | `/api/calendar/initiate` | Initiates Google Calendar OAuth flow | Admin Only |
| `POST` | `/api/calendar/disconnect` | Disconnects Google Calendar integration | Admin Only |
| `GET` | `/api/calendly/status` | Checks Calendly OAuth connection status & selected event type | Authenticated |
| `GET` | `/api/calendly/initiate` | Initiates Calendly OAuth 2.0 PKCE flow | Admin Only |
| `GET` | `/api/calendly/event-types` | Lists bookable Calendly 1-on-1 event types | Authenticated |
| `POST` | `/api/calendly/event-type` | Sets active Calendly event type for bookings | Admin Only |
| `POST` | `/api/calendly/disconnect` | Disconnects Calendly integration | Admin Only |
| `POST` | `/api/calendly/webhook` | Inbound Calendly webhook (`invitee.created`, `invitee.canceled`) | Public / HMAC Signed |
| `GET` | `/api/hubspot/status` | Checks HubSpot CRM OAuth connection status | Authenticated |
| `GET` | `/api/hubspot/initiate` | Initiates HubSpot CRM OAuth 2.0 flow | Admin Only |
| `POST` | `/api/hubspot/disconnect` | Disconnects HubSpot CRM integration | Admin Only |
| `POST` | `/api/tenant/webhook/test` | Triggers test.ping webhook to verify endpoint connectivity & latency | Admin Only |
| `GET` | `/api/tenant/team` | Returns team members and seat allocation | Authenticated |
| `POST` | `/api/tenant/team` | Invites a new team member | Admin Only |
| `PATCH` | `/api/tenant/team/{id}` | Updates team member role (Admin/Viewer) | Admin Only |
| `DELETE` | `/api/tenant/team/{id}` | Removes a team member | Admin Only |

### 5.3 Webhook Event Payload Example: Call Completed (Zapier, Jobber, Housecall Pro, GHL)
Agent Ring delivers authenticated outbound webhooks signed with HMAC-SHA256 in the `X-AgentRing-Signature` header (`sha256=<hex_digest>`), featuring 3x exponential backoff retries:

```json
{
  "event": "call.completed",
  "delivery_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "timestamp": "2026-10-17T12:00:00Z",
  "tenant_id": 1,
  "call": {
    "id": 504,
    "call_sid": "CA1234567890abcdef",
    "caller_phone": "+15555550199",
    "duration_seconds": 142,
    "category": "emergency",
    "summary": "Caller experienced acute sewer line backup in basement. Booked emergency inspection for Sunday 9:00 AM.",
    "recording_url": "https://api.twilio.com/2010-04-01/Accounts/.../Recordings/RE123.mp3"
  },
  "lead": {
    "name": "Sarah Connor",
    "phone": "+15555550199",
    "address": "1244 Elm Street, Austin, TX",
    "service_requested": "Main line sewage backup",
    "urgency": "critical"
  },
  "appointment": {
    "id": 101,
    "start_time": "2026-10-18T09:00:00Z",
    "end_time": "2026-10-18T10:00:00Z",
    "manual_notes": "Emergency main sewer line inspection"
  },
  "metadata": {}
}
```

---

## 6. Frequently Asked Questions (FAQ)

### Q: Can contractors keep their existing business phone numbers?
**A:** Yes. Contractors do not need to replace their existing business numbers. They simply enable standard Call Forwarding (such as "Forward When Unanswered" or "Forward After Hours") on their carrier (Verizon, AT&T, T-Mobile, RingCentral, Grasshopper) to forward calls to their dedicated AgentRing number.

### Q: Does AgentRing sound like a robotic IVR ("Press 1 for Sales")?
**A:** No. AgentRing is built on Google Gemini Live native speech-to-speech AI. It answers with natural human intonation, breathes, responds in under 800 milliseconds, and allows natural interruptions without robotic menus or delays.

### Q: How does AgentRing integrate with CRMs like HubSpot, Jobber, Housecall Pro, ServiceTitan, or GoHighLevel?
**A:** AgentRing features native 1-click HubSpot CRM OAuth 2.0 integration. Once connected, contacts are automatically created or updated, and complete call records with summaries and audio links are logged directly to the caller's timeline. Additionally, AgentRing provides an automated Outbound Webhook Engine compatible with Zapier, Make.com, Jobber, Housecall Pro, ServiceTitan, and GoHighLevel. Every completed call automatically dispatches an HMAC-signed JSON payload containing caller info, extracted lead fields, appointment times, and recording links with zero manual data entry.

### Q: How does AgentRing handle emergency calls?
**A:** On Growth and Scale plans, when a caller indicates an urgent issue (e.g. leaking gas, active water flooding, AC out during heatwave), AgentRing triggers a live call transfer to the business owner or on-call technician. Before bridging the caller, AgentRing plays a private whisper message summarizing the emergency so the technician is fully prepared.

### Q: Can AgentRing book appointments directly onto Google Calendar?
**A:** Yes. AgentRing connects to Google Calendar via OAuth2. It checks availability in real time to prevent double-booking and writes confirmed appointments with full caller details directly into the calendar.

### Q: Can AgentRing integrate and book appointments using Calendly?
**A:** Yes. AgentRing features full 2-way Calendly integration using OAuth 2.0 PKCE. Callers can verbally request dates and times; the AI receptionist queries available slots via Calendly's API, directly creates confirmed invitee bookings (`POST /v2/invitees`), and stays synchronized with web-booked or canceled appointments via real-time HMAC-SHA256 signed webhooks.

### Q: What happens if a contractor runs out of monthly plan minutes?
**A:** Calls are never dropped or blocked. Extra minutes are billed at a flat overage rate of $0.40 per minute. Contractors can also upgrade to a higher tier at any time from the in-app Settings dashboard.

### Q: What trades and industries use AgentRing?
**A:** AgentRing is optimized for home service contractors and trades, including plumbing, HVAC, electrical, roofing, garage door repair, pest control, landscaping, locksmiths, and restoration contractors.

### Q: Does AgentRing support Spanish or other languages?
**A:** Yes. AgentRing features native multilingual voice support across up to 97 languages powered by Google Gemini 3.8 Live. It automatically detects the caller's spoken language on the fly (e.g. Spanish, French, Tagalog, Vietnamese, Mandarin, Polish, Portuguese) and responds fluently with sub-800ms natural latency, understanding trade-specific terminology like *fuga de gas* or *tubería rota*. Contractors can also configure Bilingual (English + Spanish), Dedicated Primary Language, or English-Only modes.

---

## 7. Competitive Comparison Matrix

| Feature | AgentRing | Bland AI | Retell AI | Smith.ai | Phonely |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Target Audience** | Trade Contractors & SMBs | Developers / Engineers | Developers / Platforms | General SMBs | Solopreneurs |
| **Setup Time** | 3 Minutes (No-Code) | Days (API coding) | Days (SDK setup) | 2–3 Days (Manual script) | 15 Minutes |
| **Speech Engine** | Gemini 3.8 Live Audio-to-Audio | Pipeline (STT+LLM+TTS) | Pipeline (STT+LLM+TTS) | Human Operators | Fast TTS Pipeline |
| **Barge-In Latency** | <800ms Native | Variable (1.2–2.0s) | Variable (1.0–1.8s) | Human | 1.5–2.5s |
| **Multilingual (Up to 97 Languages)** | Yes (Auto-Detect Native) | Manual prompt config | Model dependent | Extra per-agent fee | Basic |
| **Google Calendar Sync** | Built-in Native OAuth | Custom Webhook required | Custom Webhook required | Proprietary / Extra fee | Basic |
| **Calendly 2-Way Sync** | Native OAuth PKCE + Webhooks | Custom Webhook required | Custom Webhook required | Third-party / Extra fee | Basic |
| **HubSpot CRM Sync** | Native 1-Click OAuth | Custom Webhook required | Custom Webhook required | Third-party / Extra fee | Basic webhook / manual |
| **Whisper Call Transfer** | Yes (Built-in) | Custom flow code | Custom telephony | Extra per-call fee | No |
| **Multi-Tenant Team Seats** | Yes (Admin / Viewer) | API keys only | API keys only | User seats fee | Single user |
| **Base Monthly Cost** | $49 – $199 / mo | Usage only (Complex) | Usage only (Complex) | $300 – $600+ / mo | $39 – $99 / mo |