# Agency operations — Hyperchat 1.5.2

This guide covers connected Meta lead forms, ad approvals, scheduled advertising reports, the agency overview and ad rules. Workspaces remain isolated client accounts. Owners/admins configure operations; client reviewers see their assigned reviews and reports. Keep separate clients in separate workspaces and connect each workspace to its own intended Zernio profile.

## Meta lead forms → contacts → CRM

Open **Ads → Leads → Forms**. Choose an active Meta advertising/Page connection. An Instagram-only connection does not grant Page lead retrieval permission. Reconnect through Zernio with the appropriate Page and lead permissions if necessary.

**Import an existing form:** choose Import, load the Page's forms, then select the form. Hyperchat imports a local routing configuration; it does not edit the published Meta form. Imported forms start with routing disabled. The initial list is bounded to 100 forms.

**Create a form:** save a draft with a name, HTTPS privacy-policy URL, questions and thank-you copy. Standard questions include name/email/phone; custom questions use stable keys and can have options. Saving is local. The separate **Create on Meta** action creates a provider resource. Published forms are treated as immutable; create another form for changed questions. If creation is unconfirmed, inspect the Page's forms and import the existing one. Never repeat an uncertain creation blindly.

**Map answers:** select the provider field keys and destination contact fields. Define custom fields in Contacts first. Map email when possible so repeat leads can update the correct existing contact. Configure tags and an assigned team member, then enable routing. Assignment belongs to the lead record; it does not change unrelated inbox assignments. Existing contact tags/fields are retained. Ambiguous duplicate email matches and invalid required/type/length values are held for repair instead of silently overwriting data.

In **Settings → setup**, enable advertising events and configure the Zernio webhook. Preserve the correct client profile/account scope and existing messaging events. Signed `lead.received` events are deduplicated by provider lead ID. Enabled forms also reconcile leads periodically (normally every 15 minutes, with paginated catch-up) so a missed webhook can be recovered. Delivery still depends on Zernio/Meta permissions and availability.

Choose a ready form when creating a Meta **lead generation** campaign. The form must belong to the campaign's connection. Review and approve the campaign through the usual campaign flow.

The Leads table shows answers, origin IDs, assignment and routing state. Fix mapping errors and use Retry. A lead can create/update a contact, emit `lead.received` to configured outbound webhook subscribers and reuse verified Seedly auto-push. Configure Seedly field mappings and auto-push in the existing CRM integration before expecting delivery. No lead automatically opts a contact into marketing, initiates a DM or removes an opt-out tag. Use a provider test lead with your own controlled data for live acceptance.

## Separate ad approval chains

Go to **Team & approvals → Ad approvals**. Set ordered stages such as Internal review then Client approval. Each stage can require any one or all selected reviewers. Set an optional budget ceiling with an explicit currency. The ceiling checks the reviewed budget value; it is not a billing-level lifetime spend cap.

From an ad draft, review the exact creative, targeting, budget and launch mode, then request approval. The requester cannot approve their own request. Assigned reviewers use **Ads → Approvals** or their restricted client review screen. The final approval authorizes that snapshot only; an administrator still submits the approved campaign/update. Requested future scheduling is bound to the review when specified.

Changing the draft, policy or launch mode requires a fresh request. Removing required reviewers prevents dispatch. Campaign writes recheck approval immediately before contacting the provider. Ad updates and matched rule changes use the same policy. Existing published ads are not paused merely because a policy is enabled.

## Scheduled branded reports

First build and save a layout in Analytics. Logos, sections, charts, narrative and PDF/document or slide layout reuse the existing report designer. See [Advertising reporting](/hyperchat/getting-started/reporting.md).

Open **Analytics → Scheduled reports**. Choose a layout, advertising connection, optional ad account, recipients, cadence and IANA time zone. Recipients must be current workspace members with email addresses; invite a client as a reviewer for restricted access. Weekly reports cover the last seven complete local dates. Monthly reports cover the previous calendar month; delivery dates are limited to days 1–28. Nonexistent daylight-saving times are skipped to the next valid scheduled occurrence; repeated times run once.

Configure server-side Resend credentials, verified `MAIL_FROM` and a reachable HTTPS `SITE_URL` before enabling email schedules. A localhost SITE_URL cannot be opened by remote clients. **Generate & notify recipients** is an immediate run and can email recipients even while the recurring schedule is paused. Without mail configuration, manual generation still creates a report for review.

Convex generates an immutable data/layout snapshot, stores JSON and a styled HTML artifact, and queues an email link. The recipient signs in to open it. Workspace membership and recipient assignment are checked again on read; these are not public bearer links. No OpenRouter key or AI generation is needed for scheduled output. AI-written narrative already saved in a layout remains static until you edit it; scheduled reports do not invent fresh commentary.

Report history separates artifact status from email queue/provider acceptance. Provider acceptance does not prove inbox delivery. Partial metric warnings remain visible in reports. Open a report to download its PDF or offline HTML deck; PDF generation happens in the browser. PDF pages are image-rendered, not tagged/selectable text. Decks are HTML, not PowerPoint. Email contains a secure link, not a PDF attachment.

Editing a schedule invalidates older queued work. Removed administrators cannot keep generating scheduled reports under their previous authority. Failed runs remain in history; inspect configuration and generate another run after correction. Generation is deduplicated per schedule/minute.

## Agency overview

Open **Analytics → Agency overview** for workspaces where you are owner/admin. Search clients, inspect pending approvals, unresolved leads, disconnected accounts and alerts, then open a client's workspace.

Each client performance card shows its most recent successful report selection, including its period and currency. They are cached snapshots, not an automatic all-client real-time refresh or consolidated finance ledger. Run a report or schedule a report to refresh them. Different currencies stay separate. Connection-level and account-level selections are not added together as if they were disjoint revenue. Ad disapproval and account sync alerts can also arrive through enabled signed advertising webhooks.

## Ad monitoring and bounded changes

Open **Ads → Rules**. Select a connection, ad account and campaign, then choose spend, cost per conversion or CTR; compare above/below a threshold. Set the minimum spend, exact currency, 1–30 calendar-day window and 6–720 hour cooldown. Evaluation date bounds use UTC dates and include today; provider attribution/reporting latency still applies.

Start with **Alert only**. Rules are disabled until you enable them. Enabled rules normally evaluate every 15 minutes, with bounded queue throughput. Missing/partial data, unavailable campaign or currency mismatch skip the action and record why. This is not real-time spend enforcement.

For **Pause** or **Change budget**, choose the specific ad under that campaign and use a positive minimum spend. A budget rule specifies a fixed target amount and maximum authorized amount; each change is limited to 25% of the current provider budget. Hyperchat refreshes the target from the scoped provider connection during evaluation and rechecks live budget bounds just before writing. Targets outside the bounded provider result are held rather than guessed.

If ad approvals are enabled, a matched rule creates an update draft awaiting approval. Otherwise it queues the explicitly enabled action. Pausing or editing the rule prevents its older queued work from dispatching. An existing pending/unconfirmed update blocks another update to that ad. Unknown provider outcomes are not automatically retried. Inspect campaign activity/provider state before reconciling.

Use alerts, minimum spend and cooldowns appropriate to your reporting latency. A pause/update is subject to the network and Zernio capabilities. Rules do not promise lower acquisition costs, implement platform billing caps, or replace the network's delivery controls.

## Troubleshooting and feedback

Use Help → Report a bug. Include app version, operating system/browser, the screen, steps, expected/actual behavior and a redacted screenshot. For background work include the report/rule/lead record ID and time zone/time. Do not include credentials, access links or unredacted lead/customer data. Setup issues: include Node/pnpm versions and `node scripts/doctor.mjs --json` output after reviewing it. Windows paste/CLI recovery is in [WINDOWS_SETUP_FIX.md](/hyperchat/getting-started/windows-setup-fix.md).

Report bugs at https://devlaunchlearn.com/feedback?product=hyperchat&version=1.5.2. Distinguish a provider permission/account limitation from a failed app operation. Include any visible sanitized error; do not copy raw authorization headers or environment variables.