Marketing & Leads

NIVAA integrates with Respond.io for lead management. Contacts and messages are cached locally in D1 for fast read access. All outbound messaging is done directly in the Respond.io workspace -- the NIVAA platform is read-only.

Respond.io Integration

Respond.io is the external platform used for managing WhatsApp, Facebook, and other messaging channels. NIVAA caches contact and message data in Cloudflare D1 for fast search. The integration is read-only -- all outbound messaging (templates, broadcasts, replies) is done directly in the Respond.io workspace, not through the NIVAA platform.

Authentication

The Respond.io API key is stored as a worker secret (RESPOND_IO_KEY) set via wrangler secret put. All API calls go through the server-side proxy -- the key is never exposed to the frontend.

Contact Cache

Endpoint	Method	Description
`/admin/respondio-cache/contacts`	GET	List cached contacts with search and pagination
`/admin/respondio-cache/contacts/refresh`	POST	Force full sync from Respond.io API

Auto-Refresh

The contact cache automatically refreshes if the data is more than 24 hours stale. A manual refresh can be triggered at any time via the POST endpoint.

Message Cache

Endpoint	Method	Description
`/admin/respondio-cache/contacts/:id/messages`	GET	Cached messages for a specific contact
`/admin/respondio-cache/contacts/:id/messages/refresh`	POST	Fetch and cache latest messages from Respond.io

Messages are cached per-contact and displayed in a WhatsApp-style conversation view on the contact detail page.

Geographic Distribution

Endpoint

GET /admin/respondio-cache/distribution -- returns the geographic spread of leads, tutors, and students with 3-layer location data (area, postal prefix, full postal code). Visualized as an interactive Leaflet map with D3 SVG overlay at /admin/marketing-and-comms/respondio/distribution and a postal sector heatmap at /admin/analytics/geography.

API Proxy

For advanced operations not covered by the cache endpoints, coordinators can use the raw API proxy. This forwards requests directly to the Respond.io API with server-side authentication.

Proxy Route	Methods	Description
`/admin/respondio/*`	GET, POST, PUT, PATCH, DELETE	Forwards to `api.respond.io/v2/*` with server-side auth (admin-only)

Admin Only

All Respond.io proxy and cache endpoints require admin authentication. The proxy strips the /admin/respondio/ prefix and forwards the remainder to the Respond.io API.

Supported Channels

WhatsApp -- primary communication channel for parents and tutors
Facebook Messenger -- secondary lead capture channel
Additional channels can be configured in the Respond.io dashboard

Student Lead Column

On student list pages, a lead column links directly to the corresponding Respond.io contact when a match exists between the student record and a Respond.io contact (matched by phone number or email).

Frontend Pages

Route	Purpose
`/admin/marketing-and-comms`	Marketing overview and navigation hub
`/admin/marketing-and-comms/respondio/contacts`	Contact list with table, search, and expandable drawer
`/admin/marketing-and-comms/respondio/contacts/[id]`	Contact profile with WhatsApp-style message history
`/admin/marketing-and-comms/respondio/api`	Raw API explorer with syntax-colored response panel
`/admin/marketing-and-comms/respondio/distribution`	Geographic distribution of leads, tutors, and students
`/admin/marketing-and-comms/workflows`	WhatsApp automation workflows (D3 canvas with 6 planned flows)

WhatsApp Automation Workflows

The workflows page provides a visual D3 canvas showing 6 planned WhatsApp automation workflows. These are designed to automate common communication patterns:

1 Lead nurture -- automated follow-up sequence for new inquiries
2 Session reminders -- pre-session notifications to parents and tutors
3 Feedback collection -- post-session survey delivery
4 Package renewal -- alerts when sessions are running low
5 Onboarding -- welcome sequence for new users
6 Re-engagement -- reach out to inactive parents