Topolo Messaging

What It Is

Topolo Messaging is the first-party WhatsApp Business messaging application for Topolo organizations. It supports brand workspaces, multiple WhatsApp Business phone numbers, shared inbox foundations, campaign drafts, automation definitions, and provider webhook handling.

Architecture

Messaging runs as a Cloudflare Worker-hosted React application at messages.topolo.app. It uses Topolo Auth for identity and permissions, the shared Topolo UI Kit for landing, login, signed shell, launcher, command palette, app icon, loading flows, and BugFix reporting, and a Messaging-owned D1 schema for WhatsApp domain state.

Runtime Surfaces

The primary runtime host is https://messages.topolo.app, with public routes at / and /login, signed routes for /inbox, /numbers, /campaigns, and /automations, and app-owned APIs under /api/messaging/*.

API Reference

Messaging exposes signed workspace APIs for bootstrap, numbers, conversations, campaign drafts, automation definitions, and queued outbound messages. WhatsApp webhook verification and signed event ingestion are handled at /api/messaging/whatsapp/webhook.

Auth and Permissions

Messaging uses Auth service ID srv_topolo_messaging. Access is permission-based and scoped to the signed organization unless the signed user is a Topolo global operator.

Data Ownership

Messaging owns WhatsApp workspaces, phone-number records, inbox records, contacts, conversations, messages, campaign drafts, automation definitions, outbound jobs, and webhook events. Topolo Auth owns identity, organization context, service access, launcher metadata, and login configuration.

Deployments

Messaging deploys as the Cloudflare Worker topolo-messaging on messages.topolo.app, with topolo-messaging-dispatch consuming outbound and webhook queues.

Failure Modes

• the app is not registered in Auth as srv_topolo_messaging
• the Messaging D1 database has not been provisioned or migrated
• webhook verification secrets are missing
• queue bindings are absent, leaving provider dispatch disabled

Debugging

Start with /systems/topolo-messaging, then verify the Worker custom domain, D1 migration state, Auth service row, launcher metadata, webhook secrets, and outbound queue bindings.

Change Log / Verification

• Created Topolo Messaging on 2026-04-16 as the first-party WhatsApp Business messaging app and documented the shared UI, Auth, launcher, BugFix, D1, webhook, queue, and deployment boundaries.