PlusVibe setup: required fields and first sync

Who this is for

Operators setting up the PlusVibe integration for the first time. You will need workspace admin to save the API credentials on /integrations, and at minimum editor to run sync and push leads to a campaign.

When to use this page

Read this before you sync, push leads, or open /plusvibe. If the lead data or the credentials are wrong, sync will return nothing, audits will queue with no destination, and the writeback step will never fire.

Before you start

You need the following from PlusVibe before the dashboard can do anything useful:

• An API key for the workspace (PlusVibe Settings > API keys).
• The workspace ID (PlusVibe Settings > Workspaces).
• A webhook signing secret you can paste into both PlusVibe and the dashboard.
• The Plusvibe campaign ID you will run outreach under.

In the app

1. Save credentials on /integrations

Open Integrations then choose PlusVibe in the integrations list.

1. Paste the Workspace ID (required).
2. Paste the API key. Use the real key. Do not reuse a masked line that contains only • characters and the last few digits; the dashboard treats those as no-op submits.
3. Paste the Webhook signing secret. The dashboard verifies the x-plusvibe-signature header on every inbound webhook. Use a strong, unguessable string and configure the identical value in PlusVibe when you register the webhook URL.
4. Optional: set Default campaign ID so the campaign dropdowns elsewhere in the dashboard pre-fill.
5. Click Save.
6. Click Test API key. The button should report success. Fix any error here before moving on.
7. Click List workspaces. The dropdown should include the workspace ID you pasted. If it does not, the API key does not have access to that workspace.
8. Click Register via API (or copy the displayed Webhook URL into PlusVibe by hand). PlusVibe will then POST events to the dashboard so Lead detail stays in sync with replies, bounces, and deliveries.

For the field-level UI behaviour around masked secrets and the blocklist, see Integrations (Slack, Discord, PlusVibe, and webhooks).

2. Required lead data

PlusVibe stores arbitrary key-value pairs as custom variables on each lead. The dashboard reads and writes the following:

What sync requires

When you run Sync leads for a campaign on /plusvibe, only leads that pass every check below are pulled in as audit candidates:

1. Domain signal. The dashboard reads variables.domain if set, otherwise the PlusVibe lead's built-in company_website field.
2. Empty variables.audit_url. If audit_url is already set, the lead is considered already served and is skipped.

So for a fresh sync, set domain on every PlusVibe lead and leave audit_url empty. One click pulls every unaudited lead on the campaign (Plusvibe-side ceiling is around 20,000 per call). Audits then run 8 in parallel per tenant; a 500-lead campaign typically finishes in 30 to 60 minutes.

What auto-writeback after an audit requires

The writeback runs automatically when an audit completes. It needs three things on the dashboard's lead row:

• Contact email. The writeback target is the lead's contact email, so this must be set.
• A linked PlusVibe campaign. The lead must have been synced from a campaign or pushed there from /leads or Lead detail, so the writeback knows which campaign to write into.
• A completed audit. Status audit_complete only means the pipeline finished; writeback dispatches in the same async block as completion, so under normal operation the lead transitions to email_generated within a second.

If sync pulled a lead with no email, audits will still queue but auto-writeback will not run. Add the email on the PlusVibe side, re-sync, and then either wait for the next audit or use the Run audit action on Lead detail.

3. Choosing a workflow

Two paths produce the same end state:

Path A: push leads from ReviewMySite (recommended)

1. Create or import leads in Leads with domain and contact email.
2. Open Lead detail for a single lead or use Push selected on Leads, pipeline, and emails for a batch.
3. The dashboard sends custom_variables.domain and company_website from the lead row, so you do not need to hand-edit anything on the PlusVibe side.

Path B: leads live in PlusVibe only

1. Map or create a PlusVibe custom variable named domain (a hostname or full URL is both accepted; avoid empty values).
2. Do not pre-fill audit_url. The dashboard sets it when the writeback runs.
3. Set the lead's contact email if you want auto-writeback to fire.
4. Import or create leads as you normally would. Double-check the CSV column mapping points at domain.

4. First-run checklist

Work through these in order once the credentials are saved:

1. Save configuration on Integrations > PlusVibe if you have not already.
2. Test API key. Must succeed before sync or push.
3. List workspaces. Confirms the API key sees your workspace.
4. Choose a campaign. Pick the Plusvibe campaign ID you will run under, either in PlusVibe directly or from the campaign list on /plusvibe.
5. Sync leads. On /plusvibe, run Sync leads for the chosen campaign. Every Plusvibe lead must have domain set and audit_url empty as described above.
6. Verify queued audits. On /leads, find the imported rows. They should show audit_queued quickly, then move to audit_complete or email_generated once the pipeline runs.
7. Verify auto-writeback. After an audit completes, inspect the PlusVibe lead's Lead variables panel. The 18 audit merge fields plus the body keys should be populated. The next section lists every key.
8. If variables did not update, confirm the contact email and campaign link on the dashboard lead, then use the manual Writeback action on Lead detail to retry.

The writeback contract

PlusVibe stores extra variables on the lead and renders them inside email templates using the {{custom_<name>}} token convention. Plusvibe automatically prepends custom_ to every key it receives in the writeback payload. The dashboard pushes bare keys; templates reference them with the prefix.

Built-in PlusVibe lead fields (first_name, last_name, company_name, phone_number, email) live on the lead's main record and are referenced without the prefix as {{first_name}}. A template that still renders {{custom_x}} literally is almost always missing the custom_ prefix on the template side. Reference: PlusVibe: How to personalise your emails.

The variable set the writeback pushes depends on which audit profile ran.

Outbound (slim) profile, the Plusvibe sync default

Used for cold-email prospecting. Runs five intelligence agents on Gemini Flash against four pages. Target cost roughly £0.01 to £0.03 per audit. Writes 18 audit keys plus the body keys.

Numeric and date variables (pulled directly from the audit):

API key (push)	Template token	Value
ai_citation_score	{{custom_ai_citation_score}}	AI Citation Readiness, 0 to 100
content_authority_score	{{custom_content_authority_score}}	Topical authority, 0 to 100
ux_score	{{custom_ux_score}}	UX summary score, 0 to 100
nav_clarity_score	{{custom_nav_clarity_score}}	Homepage navigation clarity, 0 to 100
brand_health_score	{{custom_brand_health_score}}	Brand strength composite, 0 to 100
tap_target_count	{{custom_tap_target_count}}	Mobile tap-target issues count
image_savings_mb	{{custom_image_savings_mb}}	Image optimisation savings available (one decimal)
sitemap_date	{{custom_sitemap_date}}	Sitemap last refreshed, "Month YYYY"
unanswered_questions_count	{{custom_unanswered_questions_count}}	Buyer questions unanswered on the site
unanswered_q_count	{{custom_unanswered_q_count}}	Duplicate of the above under the abbreviated key
audit_url	{{custom_audit_url}}	Public audit report URL
site_url	{{custom_site_url}}	Lead's domain as a clean noun phrase

LLM-generated short British clauses:

API key (push)	Template token	Value
community_source	{{custom_community_source}}	Where the most pertinent buyer question lives (Reddit, Quora, forum)
community_question	{{custom_community_question}}	One quoted question buyers ask about this market
audit_topic	{{custom_audit_topic}}	Short noun phrase for the prospect's category
stale_pages_finding	{{custom_stale_pages_finding}}	One sentence on which key pages look unrefreshed
trust_signal_finding	{{custom_trust_signal_finding}}	One sentence on trust signals present or missing
console_or_dev_flag	{{custom_console_or_dev_flag}}	One sentence on technical hygiene findings

That is 18 audit keys in total. Every slim writeback also pushes three body keys produced by a single Gemini Flash call (roughly £0.0003 per lead), generated from the audit's summary scores and top issues:

API key (push)	Template token	Value
email_subject	{{custom_email_subject}}	AI-written subject line, per-lead bespoke
email_body	{{custom_email_body}}	AI-written body. No greeting, no sign-off; Plusvibe injects both.
email_cta	{{custom_email_cta}}	CTA text, for example "View your full audit report"

Templates that reference these tokens render the per-lead AI body. Templates that ignore them still work; the 18 audit keys above remain populated identically.

Recommended template (Style B, per-variable)

This is the template shape we recommend for new campaigns. Instead of relying on one AI-written body that drops into {{custom_email_body}}, you compose the body inside Plusvibe and slot the per-lead numbers and narrative clauses into specific positions. You stay in control of the prose; the writeback only fills the data slots.

Paste this Plusvibe template verbatim as a starting point and rewrite the wording to fit your voice:

AI Citation Readiness at {{custom_ai_citation_score}}/100. When buyers ask things on {{custom_community_source}} like "{{custom_community_question}}", ChatGPT, Perplexity and Google's AI Overviews rarely point them to your site.

Content at {{custom_content_authority_score}}/100 on authority. {{custom_stale_pages_finding}}, and {{custom_unanswered_questions_count}} buyer questions go unanswered on the site.

UX at {{custom_ux_score}}/100 overall. Navigation clarity is at {{custom_nav_clarity_score}}/100, with {{custom_tap_target_count}} tap target issues on mobile.

Brand health at {{custom_brand_health_score}}/100, {{custom_trust_signal_finding}}.

On the development side, {{custom_image_savings_mb}} MB of image savings are available, your site could be faster, the sitemap was last refreshed in {{custom_sitemap_date}} and {{custom_console_or_dev_flag}}. These need fixing as they can worsen rankings and create bad experiences for your customers compounding over time.

Full audit: {{custom_audit_url}}

The six AI-written clauses are shape-tightened to slot in correctly:

• community_source is a noun phrase (Reddit, Quora threads about EV swaps).
• community_question is a buyer question ending in ?.
• stale_pages_finding is a capitalised standalone sentence with no trailing full stop (the template adds a comma).
• trust_signal_finding starts lowercase with no trailing full stop (slots in after the comma).
• console_or_dev_flag starts lowercase or with a digit with no trailing full stop (slots in after the word "and").
• audit_topic is a short noun phrase, not used in Style B but available for legacy templates.

Once your Plusvibe campaign uses this Style B template (and you do not need {{custom_email_subject}} / {{custom_email_body}} / {{custom_email_cta}}), tick Skip AI body generation on Integrations > PlusVibe. The writeback then skips the extra LLM call that produces those three keys, dropping per-audit cost and shaving 2 to 5 seconds off the writeback. The 18 merge fields above (12 audit data points + 6 narrative clauses) still ship on every audit.

The single-body approach below remains supported and is now treated as legacy. Use it only when you cannot run a per-variable template in Plusvibe (for example, an older campaign you do not want to migrate).

Per-step sequences

When a single AI body is not enough (for example: a different shape per step, with step 1 a full pitch, step 2 a shorter recap, step 3 a polite reminder), configure a per-campaign sequence. Each step gets an archetype that tells the model what shape that step's body should take. Configuration lives in tenant_integrations.config.campaignSequences and can be edited from the Sequence tab inside the campaign expand panel on /plusvibe.

Available archetypes:

Kind	Purpose	Plusvibe template references
cold_pitch_full	Full audit-led opening email	{{custom_email_subject_N}}, {{custom_email_body_N}}
snippet_recap	Brief recap of an earlier step, anchored on a different finding	{{custom_email_subject_N}}, {{custom_email_body_N}}
reminder_resend	Re-pastes an earlier step's body with a configured intro line. No LLM call for this step; the Plusvibe template composes the intro and the referenced step's body.	{{custom_email_step_N_intro}} and {{custom_email_body_M}} (where M is the referenced step)
value_add (focus: industry, benchmark, or tip)	No-pitch follow-up that gives something useful from the audit	{{custom_email_subject_N}}, {{custom_email_body_N}}
social_proof	"We have done this for similar firms" angle	{{custom_email_subject_N}}, {{custom_email_body_N}}
question_prompt	Single-question follow-up about a finding, no CTA	{{custom_email_subject_N}}, {{custom_email_body_N}}
breakup_email	Polite last note, low-pressure exit	{{custom_email_subject_N}}, {{custom_email_body_N}}

Example sequence for a 3-step campaign matching David's default cold-email flow:

{
  "campaignSequences": {
    "<plusvibe-campaign-id>": [
      { "kind": "cold_pitch_full" },
      { "kind": "snippet_recap", "referencesStep": 1 },
      {
        "kind": "reminder_resend",
        "referencesStep": 1,
        "intro": "I'm just repasting the email I sent over to you the other day in case it got buried."
      }
    ]
  }
}

Plusvibe templates would then reference:

Plusvibe step	Subject token	Body token
Step 1	{{custom_email_subject_1}}	{{custom_email_body_1}}
Step 2	{{custom_email_subject_2}}	{{custom_email_body_2}}
Step 3	anything	{{custom_email_step_3_intro}}\n\n{{custom_email_body_1}}

Step 1 is also aliased to the unindexed {{custom_email_subject}} and {{custom_email_body}}, so older templates keep rendering correctly until you migrate them. Cost stays at roughly £0.0003 per lead; one Gemini Flash call produces every LLM-required step at once, and reminder_resend steps cost nothing extra because they reuse an earlier body. Maximum eight steps per sequence.

Campaigns that have no campaignSequences entry keep the single-body legacy behaviour. You can opt in per campaign at your pace.

Full profile, dashboard customers and replied leads

Used for paying customers and for warm leads who reply (when OUTBOUND_UPGRADE_ON_REPLY=1 is set). Runs the canonical agent pipeline and writes the original 9-key contract on top of the existing 18 outbound variables. Plusvibe's /lead/data/update merges per key, so old and new keys coexist.

API key (push)	Template token	Value
audit_url	{{custom_audit_url}}	Public audit report URL
audit_summary	{{custom_audit_summary}}	One-line score summary
audit_grade	{{custom_audit_grade}}	Letter grade
top_issue	{{custom_top_issue}}	Highest-severity finding
email_subject	{{custom_email_subject}}	LLM-generated subject
email_body	{{custom_email_body}}	LLM-generated body
email_cta	{{custom_email_cta}}	Call-to-action text
audit_seo_score	{{custom_audit_seo_score}}	SEO score
audit_perf_score	{{custom_audit_perf_score}}	Performance score
audit_security_score	{{custom_audit_security_score}}	Security score

Auto-drafted warm replies

When PLUSVIBE_AUTODRAFT_REPLIES=1 and the slim-to-full upgrade audit completes for a lead in status='replied', the API generates a short British-tone reply draft (subject and body) using the prospect's reply text and the freshly upgraded audit's headline numbers, then POSTs it to Plusvibe via saveEmailDraft. The draft lands in the Unibox under the existing reply thread (via parent_message_id), ready for a human to review and send.

No auto-send ever happens. The drafter only writes drafts. You still open the Plusvibe Unibox, scan the proposed reply, edit if needed, and click send yourself.

Recommended rollout: leave PLUSVIBE_AUTODRAFT_REPLIES unset for the first week of outbound runs. Turn it on once you have seen three to five drafts and the tone holds. If a draft needs regenerating after a tone tweak, call POST /api/plusvibe/redraft-warm-reply with { leadId } and the most recent completed full audit is used to redraft.

Common pitfalls

The send-vs-writeback timing rule

Plusvibe renders email templates at send time against whatever variables exist on the lead at that exact moment. Plusvibe never re-renders a message that has already been sent, and it does not wait for a "variables ready" signal before sending.

If a lead is enrolled in a campaign before its writeback has populated the custom_* merge fields, Plusvibe will send step 1 with empty placeholders ("had a quick look at , then ran the WLW audit..."). Once that email has gone out, no amount of subsequent variable updates will fix it.

The dashboard prevents this in two ways:

1. /api/plusvibe/leads/push rejects pushes for leads that are not yet writeback-ready. The endpoint returns HTTP 409 with a notReady array listing each blocking lead and the reason. The most common reasons are:
   • status is new: "Lead has not been audited yet, run an audit first".
   • status is audit_queued: "Audit not completed yet".
   • status is audit_complete: "Audit completed but writeback hasn't run, re-audit the lead". This is unusual; it means the writeback errored mid-flight.
   • status is one of the ready set (email_generated, email_sent, opened, replied, retargeted, converted) but the lead's plusvibeLeadData.lastOutboundWriteback.variables is missing. Same remedy: re-audit.
2. When the push succeeds, the dashboard pre-populates every custom_* merge field in the same HTTP call that enrols the lead. Plusvibe's send loop sees a fully-rendered lead the first time it ticks. There is no race window.

When the push returns 409, the operator's options are to wait for the audit to finish (and the writeback to fire), or to skip the not-ready leads and push only the ready subset by adjusting the selection. The dashboard surface for this is the Push to PlusVibe action on /leads and on Lead detail.

Auto-writeback skipped silently

Auto-writeback does not run when any of the following are true on the dashboard lead row: contact email is missing, the lead is not linked to a Plusvibe campaign (no plusvibeCampaignId), or the audit profile is not slim. The dispatch in audit-result-processor.ts logs a warning each time it skips. Use the manual Writeback action on Lead detail to retry once the missing data is filled in.

Templates render {{custom_x}} literally

Either the custom_ prefix is missing on the template side (most common), or the writeback never ran for that lead. Check the lead's variables panel in Plusvibe; if the keys are populated, the template prefix is the cause. If the keys are absent, follow the readiness troubleshooting in the section above.

Step 2 and step 3 templates look empty in the dashboard summary

The Sequence tab on /plusvibe only shows the subject and a short body preview per step variation. For follow-up steps that reply in the existing thread, Plusvibe stores the subject as empty by design and the dashboard renders the literal hint Reply in thread, no new subject. The body is still present in the underlying template, just not surfaced in the summary preview.

Troubleshooting

Symptom	What to check
0 leads synced	Wrong campaign ID, or every PlusVibe lead already has audit_url set, or no domain value (variables.domain or lead domain).
Writeback button missing on Lead detail	Lead is not on a PlusVibe campaign yet (use Push to PlusVibe or sync from a campaign), or no linked audit (run or link an audit first).
Auto-writeback did not run	Missing contact email or campaign association on the dashboard lead. Audit not completed. Profile is full, not slim. PlusVibe integration disconnected or misconfigured.
Missing email or domain	Push requires email per lead. Sync needs domain and empty audit_url. Writeback needs email on the dashboard's lead row for automatic runs.
Missing campaign link	Use Push selected or Push to PlusVibe with a campaign chosen, or sync from the campaign you intend to update PlusVibe under.
Webhook errors	Webhook signing secret mismatch or missing. URL not registered in PlusVibe.
API save fails	Real API key and Workspace ID needed. Do not paste masked placeholder text.

Privacy and compliance

The operator remains responsible for lawful outreach, consent, and unsubscribe handling. Review every AI-generated email_body before sending from your mailboxes.

Related

• PlusVibe overview. The workspace Unibox, the campaign list, and the expand panel's Overview / Sequence tabs.
• Lead detail. Per-lead push, writeback, and Unibox replies.
• Leads, pipeline, and emails. Bulk push and the pipeline stages.
• Integrations (Slack, Discord, PlusVibe, and webhooks). PlusVibe form-level field behaviour.