# FormBeep Documentation

> Complete technical documentation for FormBeep - form submissions on WhatsApp

## Overview

This is the official documentation for FormBeep, a service that sends website form submissions directly to WhatsApp. These docs cover installation, integration guides, API reference, troubleshooting, and platform-specific setup instructions.

Documentation site: https://docs.formbeep.com

## Quick Start

1. **Sign up**: Create account at https://accounts.formbeep.com/sign-up
2. **Verify WhatsApp**: Send verification code from your phone
3. **Get API key**: Copy from dashboard
4. **Add script**: Paste before closing `</body>` tag
5. **Test**: Submit a form and receive WhatsApp notification

## Core Documentation Pages

### Getting Started

- **Installation**: https://docs.formbeep.com/installation/
  - Basic setup instructions
  - Script tag placement
  - API key configuration
  - Testing your integration

- **How It Works**: https://docs.formbeep.com/how-it-works/
  - Technical architecture
  - WhatsApp 24-hour window explanation
  - Two-message pattern (template + free-form)
  - Data flow and lifecycle
  - Privacy and deletion process

### Configuration

- **Customization**: https://docs.formbeep.com/customization/
  - Domain management
  - Multiple WhatsApp recipients
  - Form field filtering
  - Webhook configuration (advanced)

- **Plans & Limits**: https://docs.formbeep.com/plans/
  - Feature comparison across plans
  - Message limits and billing periods
  - Domain and recipient limits
  - Upgrade/downgrade process

### Security & Privacy

- **Privacy & Security**: https://docs.formbeep.com/privacy-security/
  - Data storage policy (temporary only)
  - Automatic deletion after viewing
  - Origin validation
  - Rate limiting
  - Honeypot bot detection
  - XSS sanitization
  - HTTPS-only communication

### Platform-Specific Guides

#### Site Builders (No-Code)
- **Framer**: https://docs.formbeep.com/site-builders/framer/
- **Webflow**: https://docs.formbeep.com/site-builders/webflow/
- **Wix**: https://docs.formbeep.com/site-builders/wix/
- **Squarespace**: https://docs.formbeep.com/site-builders/squarespace/
- **WordPress**: https://docs.formbeep.com/site-builders/wordpress/
- **Shopify**: https://docs.formbeep.com/site-builders/shopify/
- **Ghost**: https://docs.formbeep.com/site-builders/ghost/

#### Static Site Generators
- **Hugo**: https://docs.formbeep.com/static-hosting/hugo/
- **Astro**: https://docs.formbeep.com/static-hosting/astro/
- **GitHub Pages**: https://docs.formbeep.com/static-hosting/github-pages/
- **Cloudflare Pages**: https://docs.formbeep.com/static-hosting/cloudflare-pages/
- **Netlify**: https://docs.formbeep.com/static-hosting/netlify/
- **Vercel**: https://docs.formbeep.com/static-hosting/vercel/

#### Developer Frameworks
- **React**: https://docs.formbeep.com/developer-guides/react/
- **Next.js**: https://docs.formbeep.com/developer-guides/nextjs/
- **Vue**: https://docs.formbeep.com/developer-guides/vue/
- **Django**: https://docs.formbeep.com/developer-guides/django/
- **Flask**: https://docs.formbeep.com/developer-guides/flask/
- **Ruby on Rails**: https://docs.formbeep.com/developer-guides/rails/

### Troubleshooting

- **Troubleshooting**: https://docs.formbeep.com/troubleshooting/
  - Common issues and solutions
  - Form not submitting
  - WhatsApp notification not received
  - Wrong data in notification
  - Multiple notifications for one submission
  - CORS errors
  - Origin validation errors
  - Debugging tips

## Installation Code

### Basic Installation

```html
<!-- Add before closing </body> tag -->
<script
  src="https://api.formbeep.com/v1/embed/formbeep.js"
  data-api-key="YOUR_API_KEY">
</script>
```

### With Custom Success Message

```html
<script
  src="https://api.formbeep.com/v1/embed/formbeep.js"
  data-api-key="YOUR_API_KEY"
  data-success-message="Thanks! We'll get back to you soon.">
</script>
```

### React/Next.js Example

```jsx
import { useEffect } from 'react';

export default function ContactForm() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.formbeep.com/v1/embed/formbeep.js';
    script.setAttribute('data-api-key', 'YOUR_API_KEY');
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return (
    <form method="POST">
      <input type="text" name="name" required />
      <input type="email" name="email" required />
      <textarea name="message" required></textarea>
      <button type="submit">Send</button>
    </form>
  );
}
```

## API Reference

### Submit Endpoint

**POST** `https://api.formbeep.com/v1/submit/:apiKey`

Submit form data to FormBeep for WhatsApp notification.

**Parameters:**
- `apiKey` (path parameter): Your FormBeep API key

**Headers:**
- `Origin`: Your website domain (validated against allowed domains)
- `Content-Type`: `application/x-www-form-urlencoded` or `application/json`

**Request Body:**
- Any form field names and values
- Special fields ignored: `formbeep_hp`, `w2p_hp` (honeypot)

**Response:**
```json
{
  "success": true,
  "message": "Form submitted successfully",
  "reference": "a1b2c3d4e5f6"
}
```

**Rate Limits:**
- 60 requests/minute per IP
- 100 requests/minute per API key
- 60 requests/minute per user

**Error Codes:**
- `400`: Invalid request (missing fields, invalid data)
- `401`: Invalid API key
- `403`: Origin not allowed, rate limit exceeded
- `429`: Too many requests
- `500`: Server error

### Health Endpoints

**GET** `https://api.formbeep.com/v1/health`
Basic health check (returns `200 OK`)

**GET** `https://api.formbeep.com/v1/health/deep`
Deep health check (tests D1, KV, embed script availability)

```json
{
  "status": "healthy",
  "timestamp": 1709000000000,
  "checks": {
    "database": "ok",
    "cache": "ok",
    "embed_script": "ok"
  }
}
```

**GET** `https://api.formbeep.com/v1/health/embed`
Returns embed script health status

## Technical Architecture

### Stack
- **Backend**: Cloudflare Workers (Hono framework)
- **Database**: Cloudflare D1 (SQLite at edge)
- **Cache**: Cloudflare KV (rate limiting only)
- **Auth**: Clerk (JWT with RS256)
- **Payments**: Stripe
- **Messaging**: Meta WhatsApp Business API v22.0
- **Email**: Resend

### Data Flow

1. User submits form on website
2. FormBeep embed script intercepts submission
3. Script sends data to `POST /v1/submit/:apiKey`
4. Worker validates origin, API key, rate limits
5. Worker sends WhatsApp template notification via Meta API
6. Form data stored in D1 with unique reference ID
7. User receives WhatsApp message with "View Details" button
8. User taps button → opens 24h messaging window
9. Meta webhook notifies FormBeep of button tap
10. Worker fetches submission data from D1
11. Worker sends free-form WhatsApp message with full details
12. Worker permanently deletes submission data from D1

### Security Features

- **Origin validation**: Only allowed domains can submit
- **Rate limiting**: Multiple layers (IP, API key, user)
- **Honeypot detection**: Silent bot rejection
- **XSS sanitization**: All form values sanitized before storage/display
- **HTTPS-only**: No unencrypted communication
- **JWT verification**: Clerk RS256 with JWKS rotation
- **Stripe webhook verification**: HMAC-SHA256 signature validation

### Privacy Features

- **Temporary storage**: Data stored only until viewed
- **Automatic deletion**: Submission data nulled after all recipients view
- **No soft deletes**: Actual deletion, not archiving
- **7-day auto-cleanup**: Unviewed submissions deleted after 7 days
- **Minimal logging**: Only essential data logged
- **No analytics tracking**: No third-party analytics on user data

## Common Integration Patterns

### Static HTML
Just add the script tag before `</body>`.

### React/Vue/Svelte SPAs
Load script in `useEffect`/`onMounted` hook.

### Next.js/Nuxt SSR
Load script on client-side only (`useEffect`, not during SSR).

### WordPress
Add via theme footer or Custom HTML block.

### Shopify
Add via theme customization (Layout > theme.liquid).

### Form Builders (Typeform, JotForm, etc.)
Use webhook integration (if form builder supports webhooks).

## Limitations & Constraints

- **Character limit**: 1500 chars per field value (truncated if longer)
- **No file uploads**: Text data only
- **WhatsApp only**: SMS support planned but not available yet
- **Single form action**: Forms must POST to their original endpoint (FormBeep doesn't replace it)
- **Browser requirements**: Modern browsers only (ES6+ support)
- **Message limits**: Based on plan (15–5,000/month depending on plan)

## Support & Contact

- **Email**: hello@formbeep.com
- **Discord**: Message `rishikeshs`
- **Twitter/X**: @rishikeshshari
- **GitHub Issues**: https://github.com/rishikeshsreehari/formbeep/issues (if open-sourced)

## Version History

- **v1.0** (Feb 2026): Initial release
  - Core form submission flow
  - WhatsApp notifications
  - Basic dashboard
  - Stripe payments
  - Free and paid plans

## Related Resources

- **Main site**: https://formbeep.com
- **Dashboard**: https://app.formbeep.com
- **Sign up**: https://accounts.formbeep.com/sign-up
- **Blog**: https://formbeep.com/blog
- **Privacy Policy**: https://formbeep.com/privacy.html
- **Terms of Service**: https://formbeep.com/terms.html

---

Last updated: 2026-03-02

For the most up-to-date documentation, always refer to https://docs.formbeep.com