C

CorChow Lead Pipeline — Implementation Spec

Technical document for engineering & operations teams

C

CorChow Platform

Nigerian Market — Lead Generation & Conversion Pipeline

Document Type

Technical Specification

Version

1.0 — July 2026

Audience

Engineering, Ops, Marketing

Status

Production-Ready

Contents

  1. 01 Executive Summary
  2. 02 Pipeline Architecture Diagram
  3. 03 Stage 1 — Lead Discovery
  4. 04 Stage 2 — WhatsApp Verification & Scoring
  5. 05 Stage 3 — Unified Outreach (WhatsApp + SMS)
  6. 06 Stage 4 — Demo Scheduling (Google Calendar)
  7. 07 Stage 5 — Subscription & Tenant Provisioning
  8. 08 Entity Data Model
  9. 09 Configuration & Admin Controls
  10. 10 Implementation Checklist
01

Executive Summary

CorChow's lead pipeline is an automated, WhatsApp-first customer acquisition engine designed for the Nigerian restaurant and hospitality market. It replaces traditional email-based cold outreach with localized SMS and WhatsApp messaging, leveraging local API providers for superior deliverability and cost-efficiency.

The system spans five automated stages: business discovery via Google Places enrichment, WhatsApp number verification, tiered message outreach with SMS failover, automated demo booking via Google Calendar, and Paystack-powered subscription provisioning. Each stage updates the Lead entity and logs interactions for full auditability.

02

Pipeline Architecture

Discovery

fetch-nigerian-leads → Google Places LLM

Verification

verify-whatsapp-presence → UltraMsg API

Outreach

unified-outreach → WhatsApp + SMS failover

Demo Booking

schedule-demo → Google Calendar connector

Conversion

create-checkout → Paystack → webhook provisioning

03

Stage 1 — Lead Discovery

fetch-nigerian-leads

Trigger: Manual (Admin "Fetch Leads" button) or scheduled workflow.

Input: Target city tags (e.g. lagos, abuja) and daily lead limit.

Process:

  1. Loads campaign config from LeadCampaignConfig entity.
  2. Prompts LLM with add_context_from_internet=true to find real businesses in target cities.
  3. LLM returns structured JSON: name, phone, address, website, Instagram, review count.
  4. Deduplication check against existing Lead records by venue name + city.
  5. Creates new Lead entities with pipeline_stage="discovery".
  6. Auto-triggers WhatsApp verification for each lead with a phone number.

Output: Count of created, duplicate, and verified leads.

04

Stage 2 — WhatsApp Verification & Scoring

verify-whatsapp-presence

Trigger: Automatic after lead creation, or manual via lead detail panel.

Process:

  1. Normalizes phone number to E.164 format (234...).
  2. Calls UltraMsg /contacts/check endpoint.
  3. If verified: sets is_whatsapp_verified=true, stores normalized number.
  4. Recalculates lead_score using weighted indicators:

+40 pts

WhatsApp verified

+25 pts

Instagram handle found

+20 pts

10+ Google reviews

+15 pts

Website URL found

Pipeline promotion: discovery → verified

05

Stage 3 — Unified Outreach

unified-outreach

Trigger: Manual (WhatsApp/SMS buttons in lead panel) or retargeting workflow.

Channel Decision Logic:

IF whatsapp_primary AND is_whatsapp_verified:

→ Try WhatsApp (UltraMsg API)

→ IF failed: fall back to SMS (BulkSMSNigeria)

ELSE IF phone exists:

→ Send SMS (BulkSMSNigeria)

Message Templating:

Draws from LeadTemplate entity. Supports merge variables: {venue_name}, {contact_name}, {city}, {demo_link}.

Retargeting Stages:

1Initial IntroductionDay 0
2Offer Follow-upDay 1-3
3Success StoryDay 4-7
4Final Urgency CloseDay 8-14

Post-send: Updates last_contacted_at, last_outreach_channel, promotes pipeline stage, +5 lead score.

06

Stage 4 — Demo Scheduling

schedule-demo

Trigger: Manual "Schedule Demo" button in lead detail panel.

Process:

  1. Admin enters preferred demo time (YYYY-MM-DD HH:MM).
  2. Retrieves Google Calendar OAuth token via authorized connector.
  3. Creates calendar event with Google Meet conference link.
  4. Updates Lead: status="demo_scheduled", pipeline_stage="demo_scheduled", stores event ID/URL.
  5. Auto-triggers confirmation message via unified-outreach (WhatsApp or SMS).
  6. Logs LeadInteraction with demo details.

Score impact: +10 pts (max 100).

07

Stage 5 — Subscription & Provisioning

create-checkout → paystack-subscription-webhook

Checkout Initiation:

  1. Lead (now prospect) selects plan from landing page pricing.
  2. Email captured via EmailPromptModal.
  3. create-checkout validates plan + email, calls Paystack API.
  4. Returns Paystack hosted checkout URL; user redirected.

Automated Provisioning (Webhook):

  1. Paystack sends charge.success event to webhook endpoint.
  2. HMAC-SHA512 signature verified for security.
  3. Finds pending Subscription by transaction reference.
  4. Creates Organisation + initial Venue for the tenant.
  5. Activates subscription; generates paid Invoice record.
  6. Lead status updated to converted.

Fully Autonomous

No manual intervention required from payment to tenant go-live.

08

Entity Data Model

Lead

Core entity — represents a discovered business prospect

name, venue_name, email, phoneBasic identity
whatsapp_phone, is_whatsapp_verifiedWhatsApp verification state
pipeline_stagediscovery → verified → outreached → demo_scheduled → converted
statusnew → contacted → qualified → demo_scheduled → converted → lost
city_tagNigerian city targeting tag (lagos, abuja, etc.)
lead_score0-100 weighted scoring
website_url, instagram_handle, google_reviews_countDigital presence indicators
last_outreach_channel, last_contacted_atOutreach tracking
calendar_event_id, demo_scheduled_atDemo booking state

LeadCampaignConfig

Module-wide configuration & targeting

module_enabledGlobal on/off toggle
target_city_tagsArray of Nigerian city tags for targeting
whatsapp_primaryWhatsApp-first with SMS failover
daily_lead_limitMax leads fetched per run
campaign_intervals_daysRetargeting cadence [1, 3, 7, 14]

LeadTemplate

Message templates per channel & stage

nameTemplate identifier (initial_whatsapp, sms_failover, etc.)
channelwhatsapp | sms | email
stagePipeline stage 1-4
bodyMessage text with merge variables
09

Admin Controls

All controls live in the SaaSAdmin → Leads tab.

Module Toggle

Global on/off switch pauses all outreach

City Tag Selector

15 Nigerian metros available as pill toggles

Retargeting Intervals

Editable day intervals between outreach stages

WhatsApp Primary Toggle

Switch between WhatsApp-first or SMS-first

10

Implementation Checklist

Set UltraMsg secrets (ULTRAMSG_API_TOKEN, ULTRAMSG_INSTANCE_ID) in Platform Environment VariablesCRITICAL
Verify BulkSMSNigeria API token is activeCRITICAL
Confirm Google Calendar connector is authorizedCRITICAL
Confirm Paystack webhook endpoint is registered in Paystack dashboardCRITICAL
Review LeadTemplate content for brand tone alignment
Enable Lead Automation Module toggle in SaaSAdmin → LeadsCRITICAL
Select target city tags (start with Lagos + Abuja)
Run initial fetch-nigerian-leads to populate pipeline
Test verify-whatsapp-presence on sample leads
Test unified-outreach WhatsApp + SMS failover
Test schedule-demo with Google Calendar
Verify end-to-end: lead → outreach → demo → Paystack → provisioning

CorChow Platform — Lead Generation Pipeline Specification

Document Version 1.0 · Generated July 2026 · Confidential