WA Relay

Run your own WhatsApp gateway without losing control.

WA Relay is a self-hosted WhatsApp gateway for personal use, letting one user send and receive WhatsApp messages through an API and simple dashboard. It is designed for technically comfortable individuals who want automation, notifications, or personal workflow integration while keeping control of their account, data, and infrastructure.

Business Goals

  • Reach a working MVP with send, receive, and delivery status support within 4 weeks.
  • Achieve 99% successful message dispatch for valid outbound requests in the first month of use.
  • Reduce manual WhatsApp handling time by at least 50% for common personal automation workflows within 60 days.
  • Keep monthly hosting cost under USD 15 for a single-user deployment on a small VPS.
  • Attain zero critical security incidents and no data loss events during the first 90 days after launch.

User Goals

  • Send WhatsApp messages from personal automations without using a third-party gateway.
  • Receive incoming WhatsApp messages in a dashboard or webhook for personal workflows.
  • Track whether messages were delivered, read, or failed.
  • Re-authorize the device quickly if WhatsApp session expires.
  • Keep message history and logs under the user’s own control.

Non-Goals

  • No multi-tenant SaaS admin panel for teams or agencies.
  • No bulk marketing or broadcast messaging features.
  • No support for bypassing WhatsApp policies, rate limits, or account protections.
  • No voice calls, WhatsApp Business API provisioning, or official Meta BSP onboarding in MVP.

Tech-Savvy Individual Ari, 31 - Ari is comfortable with Docker, webhooks, and basic server administration. He wants a private WhatsApp bridge to connect personal alerts, reminders, and small scripts without handing data to a SaaS provider.

Tech-Savvy Individual Ari, 31

  • As a tech-savvy user, I want to connect my WhatsApp account once and keep the session running on my VPS, so that I can automate messages from my own tools.
  • As a tech-savvy user, I want a webhook for inbound messages, so that I can pipe replies into scripts or a personal bot.
  • As a tech-savvy user, I want to see delivery and read status in the dashboard, so that I know whether my messages reached the recipient.

Busy Freelancer Dina, 38 - Dina uses WhatsApp for client communication and wants lightweight automations for reminders and status updates. She is not trying to build a product; she just wants dependable personal infrastructure that saves time.

Busy Freelancer Dina, 38

  • As a freelancer, I want to schedule reminders and send templated messages, so that I can follow up with clients consistently.
  • As a freelancer, I want failed messages to retry automatically, so that I do not miss important conversations due to network hiccups.
  • As a freelancer, I want a simple interface with clear status indicators, so that I can use the system without reading logs all day.

Independent Maker Rafi, 27 - Rafi builds small internal tools and personal dashboards. He wants a reliable message relay that can be integrated into existing apps through an API and protected with a personal token.

Independent Maker Rafi, 27

  • As a maker, I want a REST API to send messages, so that I can connect my own apps and scripts.
  • As a maker, I want API keys and rate controls, so that I can prevent accidental spam from my automation scripts.
  • As a maker, I want exportable logs, so that I can debug failures and audit what was sent.

Account Connection and Session Management · High priority

  • The system must connect to a single WhatsApp account and maintain an authenticated session for personal use.
  • Use QR code login flow with session persistence across restarts.
  • Detect session expiration and prompt the user to re-scan within the dashboard.
  • Store session credentials encrypted at rest.
  • Show connection state clearly: disconnected, pairing, connected, reconnecting.
  • Prevent multiple concurrent sessions from overwriting the active identity unless explicitly re-linked.

Message Send and Receive API · High priority

  • Provide a simple API and UI for sending outbound messages and receiving inbound messages.
  • Support text messages as the MVP payload type.
  • Accept recipient numbers in E.164 format and validate them before sending.
  • Return message IDs immediately and update status asynchronously.
  • Expose webhook callbacks for inbound messages and status changes.
  • Reject malformed payloads with actionable error messages.

Dashboard and Conversation Log · High priority

  • Provide a minimal interface to view connection status, recent messages, and system activity.
  • Show inbox-style message timeline with sender, timestamp, and delivery state.
  • Allow search by phone number, message ID, or date range.
  • Display clear failure reasons when the platform provides them.
  • Support pagination for large logs and lazy loading for performance.
  • Include a health panel for session status, queue depth, and webhook delivery.

Automation and Scheduling · Medium priority

  • Enable personal workflow automation without requiring external orchestration tools for basic use cases.
  • Allow scheduled one-time messages and recurring reminders.
  • Support template storage for common message bodies.
  • Provide retry rules for temporary delivery failures.
  • Allow manual resend from the dashboard.
  • Expose cron-compatible scheduling semantics for advanced users.

Security, Audit, and Controls · High priority

  • Protect the connected WhatsApp session and prevent accidental misuse of the gateway.
  • Require API key authentication for all send and admin endpoints.
  • Allow IP allowlisting for webhook and API access.
  • Record audit logs for authentication, sends, retries, and configuration changes.
  • Provide rate limiting per API key and per recipient number.
  • Add a kill switch to immediately disable outbound sends without deleting the account.

First-Time Setup

  • Install the app with Docker Compose or a one-click VPS deploy.
  • Open the local dashboard and generate a secure admin password.
  • Scan the WhatsApp QR code from the dashboard.
  • Confirm the connection status turns green and the session is saved.
  • Send a test message to your own number and verify delivery.
  • Time to first successful message should be under 10 minutes for a prepared user.

1. Connect WhatsApp

  • The user pairs a single WhatsApp account through QR code and lands on a live connection screen.
  • Show a large QR code with auto-refresh every 30 seconds.
  • If the QR expires, provide a one-click regenerate action.
  • Block sending until the session is fully authenticated.

2. Send a Message

  • The user enters a destination number and message body or calls the API to send.
  • Validate recipient format before submission.
  • Return a preview and send confirmation before the request is queued.
  • Surface immediate errors for missing number, empty body, or disconnected session.

3. Track Delivery

  • The user monitors the message lifecycle from queued to sent, delivered, read, or failed.
  • Update status asynchronously from webhook or socket events.
  • Show a reason code when delivery fails.
  • Retry only on transient failures and label manual retry separately.

4. Receive Replies

  • Incoming messages arrive in the inbox and can be forwarded to a webhook or viewed in the dashboard.
  • Persist the inbound message with timestamp and sender metadata.
  • Allow filtering by unread, sender, or conversation.
  • Ignore duplicate inbound events using idempotency keys.

5. Manage Automation

  • The user creates reminders and recurring sends for personal workflows.
  • Support timezone-aware scheduling.
  • Warn if a schedule would send outside configured quiet hours.
  • Allow pausing or deleting a schedule without affecting message history.

Advanced and Edge Case Features

  • Multiple API keys with scoped permissions for send-only or read-only access.
  • Message templates with variables for name, date, and custom fields.
  • Delivery retry queue with exponential backoff for temporary failures.
  • Export logs as CSV or JSON for debugging and backups.
  • Quiet hours and per-recipient throttling to avoid accidental spam.
  • Session recovery helper that explains when re-authentication is required.

Design Principles

  • Clear status-first UI with connection health always visible.
  • Responsive layout that works well on desktop and tablet.
  • High-contrast states for connected, warning, and error conditions.
  • Accessible controls with keyboard navigation and readable error messages.
  • Fast initial load with optimistic UI for queueing actions.
  • Minimalistic admin-style interface that favors clarity over decoration.

Ari used to copy and paste WhatsApp reminders manually every day, which was fine until his workflow grew and mistakes started piling up. He wanted a private way to connect his scripts to WhatsApp without handing his data to another SaaS product.

With WA Relay, Ari scans one QR code, connects his account, and sends messages through a simple API from his own server. Incoming replies show up in the dashboard and can trigger his webhook, so his reminders, follow-ups, and personal automations now run with almost no manual effort.

The result is less context switching, fewer missed replies, and a system Ari fully owns. He saves time every week, keeps his message history private, and can scale the setup slightly as his personal workflows evolve.

User-Centric Metrics

  • At least 90% of new users send their first successful test message within 10 minutes.
  • At least 95% of sent messages show a final status within 60 seconds under normal network conditions.
  • At least 80% of active users use the dashboard or API at least 3 times per week after 30 days.
  • Fewer than 5% of messages require manual re-send due to avoidable app errors.
  • Average setup satisfaction score of 4.5 out of 5 in early user feedback.

Business Metrics

  • 30-day retention above 60% for early adopters.
  • Weekly active usage of at least 3 sessions per user for the core personal automation loop.
  • Conversion from installation to connected account above 85%.
  • Support requests under 2 per 100 active users per month after MVP stabilization.

Technical Metrics

  • 99.5% uptime for the dashboard and API over a rolling 30-day window.
  • P95 API response time under 300 ms for enqueue requests.
  • Outbound send worker success rate above 99% for valid requests excluding external network failures.
  • Zero unencrypted session credential storage in production.

Tracking Plan

  • track_install_started
  • track_qr_generated
  • track_whatsapp_connected
  • track_message_enqueued
  • track_message_status_changed
  • track_webhook_received
  • track_schedule_created
  • track_api_error_occurred

Technical Needs

  • Frontend built with Next.js and TypeScript for the dashboard.
  • Backend API built with Node.js and Fastify or NestJS.
  • WhatsApp session handling via a library compatible with web sessions, with abstraction to swap implementations if needed.
  • PostgreSQL for message logs, schedules, API keys, and audit data.
  • Redis for job queueing, retries, and ephemeral state.
  • Docker Compose for local and VPS deployment.
  • Encryption for sensitive session data using an application-level key or cloud KMS.

Integration Points

  • WhatsApp Web session library for connection and message events.
  • Webhook endpoints for external automation tools such as n8n, Zapier, or custom scripts.
  • SMTP or Telegram optional notification integration for session alerts.
  • OAuth or email-based admin login for local owner access if needed.
  • S3-compatible storage for backup exports and log archives if the user enables it.

Data Storage & Privacy

  • Store phone numbers, message bodies, and session data encrypted at rest.
  • Keep a clear data retention policy with configurable auto-delete for old logs.
  • Provide export and delete controls for personal data to support privacy rights.
  • Minimize PII collection to only what is required for message relay and audit.
  • Document that the user is responsible for consent and compliance with WhatsApp usage policies and local laws.

Scalability & Performance

  • Design for a single-user deployment but isolate send workers so spikes do not freeze the UI.
  • Use background queues for sends, retries, and webhook delivery to keep the API responsive.
  • Paginate message history and index phone number and timestamp fields in PostgreSQL.
  • Cache connection health and queue counts to avoid expensive polling.

Potential Challenges

  • WhatsApp session instability may interrupt connectivity; mitigate with auto-reconnect, clear re-auth prompts, and health checks.
  • Library compatibility may break after WhatsApp changes; mitigate with modular adapter design and version pinning.
  • Accidental misuse or spam risk may occur from automation; mitigate with rate limits, quiet hours, and explicit confirmation for bulk sends.
  • Data sensitivity is high because messages are personal; mitigate with encryption, access controls, and local-first deployment guidance.
  • Webhook failures could cause lost automation events; mitigate with retries, dead-letter storage, and replay tools.

Team & resourcing - Small team - 1 full-stack engineer, 1 part-time backend engineer, 1 designer on contract, part-time PM.

Phase 1: MVP Relay · Weeks 1–3

  • Dockerized app with login, QR pairing, and persistent session storage.
  • Send text message API and basic dashboard send form.
  • Inbound message capture and simple message log.
  • Connection health indicator and basic error states.

Phase 2: Reliability and Controls · Weeks 4–6

  • Delivery status tracking and retry queue.
  • API key management with rate limiting.
  • Webhook callbacks for inbound messages and status updates.
  • Audit log and encrypted credential storage.

Phase 3: Personal Automation · Weeks 7–8

  • Scheduled messages and recurring reminders.
  • Template management with variables.
  • Quiet hours and resend controls.
  • Searchable inbox and exportable logs.

Phase 4: Hardening and Launch · Weeks 9–10

  • Performance tuning, monitoring, and alerting.
  • Backup and restore guide for self-hosted deployment.
  • Security review and session recovery improvements.
  • Documentation for setup, troubleshooting, and API usage.

Paste this into Cursor, Bolt, Lovable, or v0 to start building.

Build a self-hosted WhatsApp gateway product called WA Relay for personal use.

Core product:
A single-user dashboard and API that lets someone connect one WhatsApp account via QR code, send text messages, receive inbound messages, view delivery statuses, and trigger personal automations through webhooks and scheduled messages.

Primary screens and flows:
1. First-time setup screen with admin password creation and WhatsApp QR pairing
2. Connection status dashboard showing connected/disconnected/reconnecting state
3. Send message screen with recipient phone number, message body, and send history
4. Inbox/history screen with inbound and outbound messages, search, filters, and status labels
5. Automations screen for scheduled and recurring messages
6. Settings screen for API keys, webhook URL, quiet hours, rate limits, and log retention

Data model:
User/Admin, WhatsAppSession, ApiKey, Message, MessageStatusEvent, InboundMessage, WebhookDelivery, Schedule, AuditLog, AppSetting
Fields should include ids, timestamps, phone number, body, direction, status, external message id, retry count, next run at, and encrypted session payload.

Functional requirements:
Use Node.js with TypeScript, Next.js for the frontend, Fastify or NestJS for the API, PostgreSQL for persistence, Redis for queues and retries, and Docker Compose for local/self-hosted deployment.
Implement QR-based session pairing, encrypted session persistence, outbound message queueing, webhook delivery for inbound messages and status updates, API key auth, rate limiting, retry logic with backoff, search and pagination, audit logs, and a health panel.
Design for one user on one server, but make the code modular and production-ready.

UI/UX:
Minimal admin-style interface, fast loading, mobile-friendly, accessible contrast, clear status indicators, and strong error handling for expired QR codes, disconnected sessions, malformed numbers, and failed sends.

Implementation details:
Use server actions or API routes for the UI, background workers for sending and retries, websocket or polling for live status updates, Zod for validation, Prisma or Drizzle for database access, and structured logs.
Include seed data, environment variable examples, README setup instructions, and sensible defaults for local development.

Deliver a polished MVP with the features above and clean, maintainable code architecture.

Business Idea

saya ingin membuat sebuah WA Gateway sendiri untuk kepentingan pribadi

Make My PRD

Design by The Resonance | Powered by GPC – The AI Transformation Company