Clients and portals (Agency add-on).

Quick facts

Plan

Agency add-on

Lives at

/dashboard/clients

Per-client URL

/api/agent-callback/{slug}, 16 hex chars

Per-client secret

48 hex chars, sent as X-Webhook-Secret

Public portal

/portal/{slug}, read-only, no login, custom-domain aware

Idempotency

Send external_id and retries collapse to one row

Model

Three concepts to keep straight:

• ClientAn end client of your agency, not a Ciela user. They never log in. You add them at /dashboard/clients with their name, primary contact, and monthly retainer. The server mints a unique slug + webhook secret for them on creation.
• DeploymentOne Library agent you've installed for this client. Receptionist, lead reactivation, quote generator, missed-call text-back, or custom. The deployment is your bookkeeping record, the agent itself runs in the client's n8n + Vapi (not in Ciela). Status flips between live, paused, retired.
• EventA performance datapoint POSTed by a deployed agent. Call answered, lead captured, appointment booked, message sent, message received, quote sent, or custom. Reports speak in concrete agent activity, not revenue.

Walkthrough

POST /api/agent-callback/<slug>
X-Webhook-Secret: <secret>
Content-Type: application/json

{
  "event_type": "appointment_booked",
  "deployment_id": "<optional, from /dashboard/clients/[id]>",
  "external_id": "<optional, your idempotency key>",
  "metadata": { "customer": "Jane", "service": "Cleaning" }
}

What you see on the roster

The top of /dashboard/clients shows two rollup cards across every client at once, so you can answer "how is my book of business doing?" without opening a client.

• Active clientsCount of clients with status = active. Total roster count (including paused + churned) shows below.
• Events (30d)Webhook events received across every deployment in the last 30 days. The denominator behind whether your AI agency is actually delivering volume to clients.

Each row in the roster shows that client's own retainer amount (a self-reported number you set per client, for your own bookkeeping), live vs total deployments, and 30-day event count. Retainer is per-client context, not rolled up across the roster, because the number is operator-typed and shouldn't be confused with billing-grade MRR. Click any row to open the per-client detail.

Tune a live agent (Production Agent Tuning)

Once a Theo Production voice agent is live for a client, you can change how it behaves in place, without re-provisioning or re-sending the call link. Do it from Ciela chat ("open Bella Nails' receptionist, it keeps booking acrylic fills as full sets, fix it and patch it live") or from the Tune panel on the client's deployment row. Ciela rebuilds the assistant's system prompt and PATCHes the live Vapi assistant in place, keeping its booking and availability tools wired, then records a version you can review and suggests a phrase to retest with.

• What you controlThe prompt layer only: behavior profile and tone, service rules (what the agent asks before booking), FAQ answers, pricing guardrails, and escalation rules. Edit them as plain rules in the Rules / FAQ / Pricing / Escalation tabs, or describe the fix to Ciela in chat.
• Patch liveRebuilds the prompt and updates the live Vapi assistant in place. Every patch is logged under the Versions tab with what changed and whether the live update succeeded.
• TestHands you a suggested scenario to retest the agent with and opens the assistant in Vapi so you can run the call.

Set your agency brand

The public portal at /portal/{slug} renders under your agency's brand, not Ciela's. Set this once under account settings, Brand tab and every client portal you share from then on inherits it.

• Agency nameRendered in the portal footer as "Report by <Agency name>". Leave blank for a generic "Performance report" footer.
• LogoUpload directly from your machine, square 256x256 works fine. Falls back as the header image when a client has no per-client logo of their own. JPG, PNG, WebP, SVG, or GIF up to 2 MB.
• Brand colorAny CSS color (hex, rgb, hsl, named). Drives the accent on metric numbers, agent cards, and the activity feed inside the portal. Defaults to champagne (#d4a574) if unset.

Filtering the detail view

The per-client detail page is where you have monthly review conversations. Three controls narrow what you're looking at:

• Date rangePill toggle at the top: 7 days, 30 days, 90 days. Drives the metrics rollup card (Events count, type breakdown). The activity feed itself always shows newest first regardless of range, so you can still see what just happened.
• Event-type chipsClick Calls · 22, Appointments · 21, etc. to narrow the activity feed to just that event type. Counts on the chips reflect the current date range. Only types that actually have at least one event in the window appear, no empty filters.
• Per-agent chipsSurface only when a client has more than one deployment. Click an agent name to scope the feed to events that deployment posted (events without deployment_id attribution are excluded when this filter is active).
• Load 50 moreThe feed starts with the newest 50. Load 50 more paginates backwards using an occurred_at cursor. Works with filters applied: paginated pages respect the current chip selection.
• Clear filtersA single chip appears when any type or per-agent filter is active. One click resets both back to All / All agents.

Monthly summary (the portal hero)

The detail page also drives the narrative that opens the public portal. Claude reads the client's event ledger + active deployments for a period you pick, writes a 60-120 word summary in the agency voice, and hands it back to you to edit before publishing. The end client opens /portal/{slug} and sees the story you approved sitting above the metrics, not a raw activity log. Saved summaries replace the old activity-feed approach to monthly reporting.

• Pick a periodDropdown next to Generate summary: This month, Last month, Last 30 days, Last 90 days. Drives which events Claude reads. The period label (eg "January 2026") is rendered on the portal next to the summary so the client knows what window they're looking at.
• GenerateOne Haiku call, a few cents per generate. Claude reads the events for the chosen period plus the previous window of the same length so it can speak to trend ("calls trended up vs the prior month"). Returns a one-or-two-paragraph draft in plain prose, no markdown, no em dashes, no platform names. You see it as an editable text field, not auto-published.
• EditThe draft is operator-editable. Tighten the wording, swap a number, change the closing sentence, anything. The agency voice is yours to set, Claude just gives you a starting point that's grounded in the actual ledger so you're not staring at a blank box.
• PublishSaves summary_text + summary_period_label to the client row and stamps summary_generated_at server-side. From that moment, anyone with the portal URL sees it at the top of the report. Until you publish, the portal renders without a summary, just the metrics carry the page.
• RegenerateGenerating a new summary does not auto-replace the published one, you have to edit + publish again. So the client never sees a draft you didn't sign off on. The detail page shows a 'Generated X days ago' hint next to the saved summary so you know when it's time to refresh.
• ClearEmpty the text field and save to wipe the summary off the portal. The portal renders again without the hero, metrics only. Useful when a client period is too soft to summarize, or when you're between months.

Lifecycle and statuses

Clients and deployments each have their own status field. Use them to keep historical metrics intact while reflecting current reality.

• Client: activeRetainer is being paid, agents are deployed and running. Counts toward the roster's Active clients rollup.
• Client: pausedTemporary hold (client took a break, frozen for a season, mid-pivot). Stays on the roster, drops out of the Active count. Set this when you want metrics history preserved but no longer want the client counted as live.
• Client: churnedRelationship ended. Stays on the roster as historical record. Don't delete the client unless you also want to lose every event ever posted for them, the cascade is aggressive on purpose to keep tables clean.
• Deployment: liveAgent is currently running in the client's infrastructure and posting events. Default on creation.
• Deployment: pausedTemporarily off (maintenance, awaiting a client config change). Events you POST while paused still land in client_events, the status is informational. Flip back to live when you resume.
• Deployment: retiredPermanently decommissioned. Flip to this instead of deleting the row when an agent install ends, otherwise the events that posted under it lose their attribution (the deployment_id FK is ON DELETE SET NULL, so the events themselves survive but the link is gone).

Event types

• call_answeredAgent picked up an inbound call (Vapi assistant or n8n handoff).
• call_completedCall wrapped up. Use this for end-of-call metrics if your runtime distinguishes pick-up from completion.
• conversation_handledChat conversation handled. Use this once per concluded thread, not once per message.
• lead_capturedA new lead got written to the CRM. Add metadata to identify source (form, missed-call recovery, etc.).
• appointment_bookedCalendar event created. The agent booked a real appointment.
• message_sentOutbound text or chat message dispatched by the deployed agent.
• message_receivedInbound message handled by the deployed agent.
• quote_sentQuote / estimate delivered to a prospect by the deployed agent.
• customAnything else. Put a descriptive label in metadata so the activity feed reads sensibly.

Per-client URL + secret model

Privacy notes for the portal

• What the client seesTheir name, your agency brand, aggregate counts by event type, the deployments running for them, and per-event metadata you chose to send. Nothing about your other clients, nothing about your retainer.
• Metadata is visibleAnything you put in the metadata object on the webhook event shows up on the portal feed. Don't post PII you don't want the client to see. The portal is effectively a public URL guarded only by the slug's non-enumerability.
• AuthenticationNone. The slug is the secret. Treat the portal URL like a shared Google Doc link, share it deliberately. Rotating the webhook secret stops anyone posting events with the old one but does not change the portal URL, to take a portal offline entirely you delete the client.

Common failure modes

Keep reading