# Hyperchat user handbook — 1.5 beta

For installation, read SETUP.md. Coding agents should start with AGENT_SETUP.md. This guide is included offline and published at https://devlaunchlearn.com/hyperchat/getting-started. Features depend on your installed version, role, account eligibility and provider access.

## Workspaces and account connections

Start every task by checking the workspace and account name. Each client has separate contacts, media, templates, posts and access.

### Set up a client

1. Create or switch workspace from the top-right workspace menu. Use a recognizable business or client name.
2. As the installation operator, open Workspace settings → Installation setup and assign the client’s Zernio profile.
3. Connect the required accounts and sync. Check their names and handles before preparing content.
4. Invite the client’s team through Team & approvals. Give client reviewers review access rather than administrator access.

Use a different profile/workspace for each client. A social publishing connection does not automatically include advertising, inbox or analytics permissions.

### Find your tools

1. Use Conversations for messages, Contacts for customer records, Automations for workflows, and Publishing for posts and advertising.
2. Open Publishing’s navigation for Accounts, calendar/queue tools, Analytics, Approvals and Ads. Ads contains Campaigns, Templates and Research.
3. Use the workspace menu for Settings, Team & approvals, and Help & feedback.

Labels and available controls depend on the installed version and your role. This handbook covers the 1.5 beta; consult the release notes in your download.

## Manage conversations and customer records

Use the shared inbox for human replies, triage and customer context.

### Organize and reply

1. Open Conversations and select an account or folder: open, unread, mine, unassigned, flagged, closed or all.
2. Select a conversation; claim it or assign an eligible teammate, flag important threads, add tags, and close resolved requests. Bulk actions help organize several conversations.
3. Use the customer details panel for contact fields and private notes. A note is internal; it is not sent to the customer.
4. Write a reply or choose a saved reply. Use the composer tools for emoji, images, GIFs and recorded audio where that channel supports them. Preview attachments before sending.
5. Use human takeover when a teammate needs to handle an automated conversation. Check opt-out and messaging-window restrictions if Send is unavailable.

Rich messages differ by platform. GIPHY needs your workspace key; microphone recording needs browser permission and a secure context. A recorded audio attachment may not appear as a native voice bubble on every channel.

### Create custom fields

1. Open Contacts → Custom fields. Choose a clear key, label, type and optional group, description or placeholder.
2. Choose from text, long text, number, currency, date, date/time, boolean, dropdown, multiple choice, email, phone or URL. Add choices when required.
3. Preview the input and save. Set required-on-create only for information every new contact can supply.
4. Open or add a contact; fill contact details, tags and grouped custom fields. Automation questions and API writes use the same definitions.

Existing field keys/types and choice values are protected to keep saved records valid. Create a new key for an incompatible change; archive obsolete definitions to preserve historical values. Importing a contact does not create a social conversation or permission to message them.

## Build and troubleshoot automations

A template is an editable draft. It begins replying only after you select an eligible account and publish it.

### Create a workflow

1. Open Automations, choose a starter or create a workflow, and select Send from using the connected account’s name.
2. Choose a supported trigger: keyword, exact/prefix match, first incoming message, fallback, Instagram story reply/mention, or button payload where available.
3. Add messages, waits, questions, conditions, tags, custom-field updates, notes, flags/status changes or human handoff. Connect the intended forward paths.
4. For a question, choose the field and answer type. Add a condition after the answer to route the conversation. Rich controls are also available in message steps.
5. Use Test flow to inspect the route, review every link and branch, then Save draft or publish explicitly. Test flow does not send a real DM.
6. Send a new matching DM from another social account. Check Conversations and Run history, including captured answers and delayed steps.

Workflows support up to 40 steps and forward branches, not arbitrary loops. Publishing records a version; editing the draft does not change the running version until republished.

### Comment-to-DM

1. Choose the Instagram/Facebook comment trigger and your connected sending account.
2. Scope it to a selected test post or the intended supported posts, then set the keyword and one private text reply with your link.
3. Disable any overlapping Zernio-native comment rule for those same comments.
4. Publish after review and add a fresh matching comment from a different account. Inspect the delivery record.

The initial private reply is plain text, once per comment within the supported window. The recipient must reply before a separate DM conversation can continue. New-follower DMs and TikTok DM automation are not supported.

### When a workflow does not run

1. Confirm it is published and that the sending account, trigger, keyword and post scope match the new event.
2. Check webhook subscriptions/delivery and then the run record. Historical/imported messages are not a fresh trigger.
3. Check human takeover, opt-out, reply-window eligibility, missing field values and provider errors.
4. Pause the workflow before editing a problematic live flow. For uncertain sends, inspect provider history before deciding what happened.

Do not automatically retry an ambiguous send: the customer might already have received it.

## Compose, schedule and queue social posts

Create a draft first, then review each destination’s actual format and account requirements.

### Compose a post

1. Open Publishing and start a post. Select the intended connected accounts.
2. Write the shared caption, then customize per-account text, media and options. Select the supported format for each account.
3. Upload or select media, arrange its order, and check destination-specific previews and validation messages.
4. Save the draft. If your workspace requires approval, request review of this saved revision.
5. Choose a date, time and timezone to schedule, use an available queue slot, or explicitly confirm publishing now.
6. Check the calendar, job status and provider result after dispatch. Refresh account status when a connection expires.

Scheduling is handled by the backend; closing your browser does not cancel a scheduled job. Required current approvals and account eligibility are checked again when it dispatches.

### Carousels, Reels and video

1. Choose a destination and supported post format before preparing media.
2. For a carousel, add and order the individual slides/assets. Check the platform’s allowed media count and combinations.
3. For a Reel or video post, supply an actual video file with the destination’s required dimensions, duration and encoding. A script alone is not a video.
4. Review cover, caption and available channel-specific options, save, approve if needed, then schedule.

The app supports Zernio publishing adapters for X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Google Business Profile, Telegram, Snapchat, Discord, Slack and WhatsApp. This does not imply every format, inbox feature or analytics metric exists on every channel.

### Queues and failed delivery

1. Configure the account’s timezone and posting slots before adding approved content to its queue.
2. Review the assigned slot in the calendar. Check destination-specific edits before changing a scheduled post.
3. Read the exact job error if delivery fails. Reconnect expired accounts or correct validation failures before preparing a new attempt.

When delivery is uncertain, compare provider history first. Do not blindly duplicate or retry a potentially published post.

## Create graphic templates and media

The 24 graphic presets use editable layouts and do not require an AI key.

### Create reusable artwork

1. Open Ads → Templates → Graphics and choose a layout: split, poster, offer, quote, event, checklist, product or editorial.
2. Replace all example text, quotes, event dates and offers with your approved content. Set brand colors and optionally upload a photo and logo you have rights to use.
3. Choose square (1080×1080), portrait (1080×1350), story (1080×1920), or landscape (1200×628). Shorten text that does not fit.
4. Save design to keep an editable workspace copy. Download PNG for a local file, or Save PNG to media to reuse it in Hyperchat.
5. In a post, use Media → Templates. In a Meta campaign, choose Create from graphic template or use the starter’s bundled artwork.

These are guided static layouts, not a freeform design canvas or video renderer. For a carousel, create/export each slide and order the resulting assets in the composer. Photos/logos accept PNG, JPEG or WebP up to 15 MB.

### Use AI for creative work

1. Add your OpenRouter key and eligible writing/media models in Settings → AI tools. Set your provider-side spending limit first.
2. Choose the intended output: caption, script, image, carousel content or eligible video generation. Supply the business, offer, audience, format and constraints.
3. Review generated claims and facts. Watch the job result; download or select completed media before attaching it to a draft.
4. Check the destination preview and media validation before scheduling or using the result in an ad.

Model access, supported modalities, credits and pricing vary. Text models generate copy or scripts, not finished video. Paid media generation has not been certified across every model/platform.

## Create and manage advertising campaigns

Advertising uses separate account permissions and provider capabilities. Start with a saved draft and a deliberately small approved test budget.

### Connect advertising

1. In Publishing’s account connection controls, connect the required advertising network through Zernio and complete its authorization.
2. Confirm the advertising account, business identity, currency, billing and required network permissions. Sync the account into the correct client workspace.
3. Open Ads → Campaigns, select the advertising connection and Refresh ads.

The guided template builder covers Meta traffic and Google Search. Other connected networks use the supported advanced campaign fields; available actions vary by network and Zernio access. A connected Instagram profile alone does not grant Meta ad-account access.

### Build a Meta campaign from a template

1. Open Ads → Templates → Campaigns. Choose a Meta starter from the 30 business categories and select Build campaign.
2. In Client, replace the business, service, location and offer variables. Use truthful claims and a working destination URL.
3. In Creative, edit the copy, headline and call to action. Customize the bundled artwork or select your own approved image.
4. Choose Use this artwork to prepare the full-resolution image for the draft. If client details or the design change, prepare it again so the image matches the final copy.
5. In Budget & account, select the intended advertising connection and required identity/account fields, review currency, enter the daily budget and countries, and complete all validation requirements.
6. In Review, inspect the rendered creative, destination, budget and exact draft settings. Save the campaign draft.

Saving a draft does not create an ad on the network. The 30 Meta starters include editable artwork; they are original starter recipes, not ads with proven performance.

### Build a Google Search campaign

1. Choose a Google Search starter, fill the client variables and destination, and customize the headline/description fields and keywords supplied by the template.
2. Select the connected Google Ads account, currency, daily budget and supported targeting settings. Resolve any account-specific validation requirements.
3. Review the search-ad copy and exact draft settings, then save.

Google Search starters are text ads; they do not use Meta-style image creative. Google account eligibility and provider support determine which targeting and campaign settings are accepted.

### Review, create paused, or launch

1. Return to Campaigns → Campaign drafts & activity and open the saved draft.
2. Review the connected account, creative media, destination URL, countries, daily/lifetime budget type, currency and exact campaign settings.
3. For a paused test where supported, leave Launch active and allow the network to spend this budget unchecked. Confirm the settings and choose Create paused campaign.
4. To deliberately spend, select the active-launch option, review again and confirm Launch campaign. The network may begin delivery and charging immediately.
5. Inspect the job/provider result. Refresh ads and confirm the resulting campaign state on the network before further changes.

Pinterest and X require explicit active launch in the current adapter; there is no paused creation route for those adapters. Post approval chains do not approve ad spend. No advertising campaign was live-launched as part of the installation test.

### Manage existing campaigns

1. Select the correct advertising connection and Refresh ads. Open the campaign/ad you intend to change.
2. Review its current state and supported budget/status controls before saving a change.
3. Inspect Campaign drafts & activity and refresh to confirm the provider accepted the change.

Do not assume a submitted change took effect until its result is confirmed. Advanced campaign setup accepts network-supported options JSON; use the linked Zernio reference and the native Ads Manager for unsupported controls. Hyperchat does not replace every native Ads Manager feature.

## Research ads and keywords

Research is inspiration and planning data. It does not reveal a competitor’s private revenue, conversions or ROAS.

### Search and save research

1. Open Ads → Research. Select the research tool, search terms and available country/date filters.
2. For Meta, search the archive and inspect the returned advertiser, text and available source/creative information.
3. For Google keyword ideas, select an eligible connected Google Ads account and enter the seed terms or supported inputs.
4. Save useful results to a board with notes, then export CSV where offered. Use your own assets and claims when turning research into a campaign.

Zernio’s Meta commercial archive covers ads delivered in the EU/UK; it does not supply US-only commercial coverage. Billing eligibility may require a payment method. Image/video previews depend on usable media returned by the source; some results contain text or an original-ad link only. The extra US visual-research provider is not enabled in this release. Never describe missing media or metrics as available.

## Teams, client reviews and approval chains

Invite only the people who need access to that client workspace.

### Invite your team

1. Open the workspace menu → Team & approvals. Enter the teammate’s email and choose owner-managed administrator, inbox agent or client reviewer access as appropriate.
2. Create the invitation. Copy and privately share the link, or explicitly select invite email when your installation’s Resend sender works.
3. The recipient signs in or creates an account using that email and accepts the invitation. Revoke unused invitations and remove access when a teammate leaves.

Links expire after seven days. Client reviewers only see requests assigned to them; they cannot see inboxes, contacts or credentials. Administrators cannot elevate someone else to administrator.

### Set an approval chain

1. Add up to five ordered stages under Team & approvals. For each, select reviewers and choose any one or every selected reviewer.
2. Enable and save the policy. Save a post and choose Review post → Request approval; optionally add a deadline.
3. Reviewers open Approvals, inspect the saved snapshot and approve the active stage or request changes with a note. Authors cannot approve their own requests.
4. After all stages pass, an administrator reviews the publish time and schedules, queues or publishes.

Editing content, changing policy or removing a required reviewer invalidates the old approval. Dispatch checks approval again. These chains cover social posts, not advertising budgets.

## Read analytics and export reports

Publishing → Analytics contains **Advertising**, **Social accounts** and **Connections**. For campaign/account reports, open Advertising or Ads → Reports. Choose an advertising connection, account and dates; inspect current/prior metrics, daily trends, campaign → ad-set → ad details, account status and supported audience breakdowns. Filter by currency before comparing monetary totals. Export CSV or print the report. The full walkthrough and reporting limits are in [Advertising and account reporting](/hyperchat/getting-started/reporting.md).

Use **Build report** for custom layouts, branding, charts, narrative, PDF and HTML presentation exports. Report settings are saved in the builder; administrators can set a workspace default. The AI tab can suggest a report if your workspace has OpenRouter configured. AI is optional.

For organic publishing reports, open Social accounts.

### Create a report

1. Choose the workspace/account and a 1–90-day UTC range. Compare with the previous equal-length period if useful.
2. Review impressions, engagements, reported reach, top posts, daily breakdowns, followers and historical posting-time suggestions.
3. Export CSV or use the print-friendly report for client review. Check the retrieval timestamp and any unavailable values.

Reports use publish-date attribution: lifetime metrics for posts published in the range, not engagement received on each day. Summed post reach is not unique audience size. Missing metrics stay unavailable; follower growth needs at least two observations. Reports may be cached for five minutes. Workload counts such as open conversations and overdue approvals are separate from social metrics.

## Developer API and CRM integrations

Use workspace-scoped keys for server-to-server integrations; keep them out of public browser code.

### Connect your own system

1. Open Settings → Developer API as an owner/administrator. Create a key with only the required scopes and an appropriate expiry; securely save it when shown.
2. Use the base URL https://YOUR-CONVEX-DEPLOYMENT.convex.site/api/v1 and an Authorization: Bearer header. Read docs/openapi.json in your install folder for request/response schemas.
3. Read contacts, fields, conversation metadata/messages or the event feed with cursor pagination. Create/update contacts and create fields with the required write scopes.
4. Send a stable Idempotency-Key for writes. Use expectedRevision on contact updates; handle conflicts explicitly. Revoke keys when no longer needed.

API v1 does not expose outbound customer messaging or workflow publishing. Supported outbound events are contact.created, contact.updated and message.received. A developer must configure the authenticated webhook subscription, verify HMAC signatures and deduplicate event IDs; see docs/CRM_AND_API.md.

### Seedly CRM

1. Have your developer read docs/CRM_AND_API.md for the exact supported backend functions, scopes, mappings, sync and webhook setup.
2. Use your own Seedly instance and sub-account with a scoped server-side key. Start with a controlled contact record and review field mappings/conflict behavior.
3. Enable only the required contact, deal/pipeline or task operations after confirming the remote configuration.

The Seedly integration is backend-only; there is no finished connection form or deal-board UI. Its provider contracts are tested with fixtures, not a live customer Seedly deployment. Do not expect a one-click connected CRM on a fresh install.

## Report bugs and follow fixes

Use the DevLaunch Build Board as the shared record for bugs, feature requests and release follow-up.

### Submit a useful bug report

1. Open the workspace menu → Help & feedback. Copy the report template; it includes your app version and current section.
2. Open the Build Board link, choose Hyperchat and verify your email. Choose Report a bug.
3. Use a specific title such as “Campaign draft loses country after reopening.” Include numbered steps, expected result, actual result/exact error, browser/OS, frequency, version and whether you customized the code.
4. Add a redacted screenshot or recording as an HTTPS link in the evidence field. The board takes a link; it does not upload the file for you.
5. Submit and follow the report. Keep follow-up details in the same thread and retest when the team marks a fix with its release version.

Bug reports are private to the reporter and DevLaunch team. Feature ideas may become public after review; supporting links and version details remain private. Never include API keys, bootstrap/invite tokens, environment files, full customer conversations or sensitive account data.

### Collect safe diagnostics

1. From the install folder, run node scripts/doctor.mjs --connected --json. Review its output before sharing.
2. Attach the relevant exact error with secrets removed. Say which setup step failed and what you tried.
3. For urgent login, workspace-isolation or duplicate-send problems, say so in the first line. Pause the affected automation/schedule if you can do so safely and preserve the run details.

Doctor reports configuration checks without values and does not upload anything. It cannot verify live credentials or message delivery. DevLaunch does not automatically receive the private logs in your buyer-owned backend.

### What happens next

1. The team reviews the report and may ask for a minimal example or additional redacted evidence.
2. Track replies, status and release details on the board. One report per issue keeps the history useful.
3. After updating, repeat your original reproduction steps and report whether the issue is resolved.

For a feature request, describe the task you are trying to finish, who needs it and a concrete example. Do not put a private bug’s customer details into a public feature idea.

## Updates, backups and ongoing checks

Treat your source, database and provider configuration as a system you operate.

### Apply an update

1. Read the new release notes and compare the version in package.json. Keep a copy of your current source and record your customizations.
2. Back up the relevant Convex data using its supported export/dashboard process. Store backups and deployment secrets privately, outside Git and public downloads.
3. Test the update in a separate development checkout/deployment. Merge customizations deliberately and preserve the supplied lockfile.
4. Run frozen dependency installation, doctor and pnpm check. Test owner sign-in and the workflows you actually use.
5. Deploy the matching backend before the frontend. Confirm public frontend URLs match the intended backend and repeat a controlled live check.

Do not rerun first-owner bootstrap or rotate secrets as a routine upgrade. Database/schema changes can make rollback more complex than restoring old frontend code; check release-specific migration instructions before deployment.

### Routine operator checklist

1. Check failed/uncertain jobs, expiring connections, pending approvals and incoming bug reports.
2. Monitor Convex, Zernio, email and OpenRouter usage and provider limits. Keep provider-side AI spend limits current.
3. Review memberships, invitations, API scopes/expiry and retained customer data.
4. Keep a known-good test account/workflow so reconnects and releases can be checked without using customer campaigns.

The buyer controls retention, backup policy and access. A successful unit test or build is not a guarantee of provider delivery or account eligibility.