# User Guide

Welcome to WAPI Scheduler! This guide helps you get started scheduling WhatsApp messages without writing code.

## Table of Contents
- [Sign Up](#sign-up)
- [Add a WhatsApp Number](#add-a-whatsapp-number)
- [Create Your First Campaign](#create-your-first-campaign)
- [Manage Contacts](#manage-contacts)
- [View Reports](#view-reports)
- [Billing](#billing)
- [FAQ](#faq)

---

## Sign Up

1. Visit `https://app.yourdomain.com`
2. Click **Sign Up**
3. Enter your email, name, and password
4. Check your email for a verification link (optional)
5. Log in

You start on the **Free** plan: 50 messages per month, 1 WhatsApp number.

---

## Add a WhatsApp Number

Your account needs at least one connected WhatsApp number to send messages.

1. In the dashboard, click **Sessions** in the sidebar
2. Click **Add WhatsApp Number**
3. Give it a name (e.g., "My Business Phone")
4. Click **Generate QR Code**
5. Wait a few seconds for the QR code to appear
6. Open WhatsApp on your phone
7. Tap **Settings** → **Linked Devices** → **Link a Device**
8. Scan the QR code with your phone
9. Once connected, the status will show **Connected**

> **Note**: Keep your phone connected to the internet. If your phone goes offline, the session will disconnect and you'll need to re-scan.

---

## Create Your First Campaign

A campaign is a set of messages you want to send to multiple contacts.

### Step 1: Prepare your contacts

You can:
- Add contacts manually (see below)
- Import a CSV file: Contacts → Import CSV

CSV format should have columns: `name`, `phone` (in E.164 format like `+85212345678`). Optional: `email`, `tags`.

**Important**: You must have consent to message these numbers. WhatsApp may ban numbers that send spam.

### Step 2: Compose your message

1. Click **Campaigns** → **New Campaign**
2. Enter a campaign name (for your reference)
3. Select which WhatsApp number to send from (dropdown)
4. Choose message type:
   - **Text** - just type your message
   - **Image** - upload an image and add optional caption
5. Write your message. You can use placeholders:
   - `{name}` - inserts contact's name
   - `{custom_field}` - if you added extra columns in CSV, e.g., `{order_id}`
6. Click **Preview** to see how it looks for a sample contact

### Step 3: Select recipients

You can pick from:
- **All contacts** (everyone in your address book)
- **Filtered by tags** (e.g., only contacts tagged "vip")
- **Individual selection** (checkbox list)

Choose your target list.

### Step 4: Schedule

Choose when to send:
- **Send now** - starts immediately
- **Schedule for later** - pick a date/time (in your timezone)
- **Recurring** - daily, weekly, or monthly (Pro+)

Click **Create Campaign**. If you chose "Send now", it will start within a minute.

---

## Track Campaign Progress

In **Campaigns** list, you'll see status:
- **Draft** - not yet scheduled
- **Scheduled** - waiting for start time
- **Running** - currently sending
- **Completed** - all done
- **Failed** - stopped due to error

Click a campaign to see:
- How many messages sent vs delivered vs read
- Which contacts received it
- Errors for failed messages

---

## Manage Contacts

### Add a single contact

1. Go to **Contacts**
2. Click **Add Contact**
3. Fill name, phone (with country code, e.g., `+1` for US, `+852` for HK), optional email
4. Add tags (comma separated) like "customer", "friend"
5. Save

### Import many contacts

1. Click **Contacts** → **Import**
2. Upload a CSV file
3. Map columns: tell us which column is name, phone, email
4. (Optional) Apply a tag to all imported
5. Click **Import**
6. You'll see a progress page. Large imports run in background; refresh to check status.

### Consent

We require that you have permission to message each contact. During import, you must confirm you obtained consent (e.g., they opted-in). For manual additions, you should record how consent was obtained (in the contact's record we'll add this later).

If someone replies **STOP** to your message, we'll automatically opt them out and they won't receive future campaigns.

---

## Messaging Limits

- **Free**: 50 messages per month, 1 active WhatsApp session
- **Pro**: 2,000 messages per month, 3 sessions
- **Business**: 10,000 messages per month, unlimited sessions

Counters reset on your billing date (usually the 1st of month). You can see your usage in Dashboard or Billing page.

If you hit your limit mid-campaign, the remaining contacts won't be sent. Upgrade to continue.

---

## Schedule

You can schedule a campaign to any future time. The system will automatically start it at that time. Recurring campaigns (Pro+):

- **Daily**: send every day at same time
- **Weekly**: on specific weekdays
- **Monthly**: on a specific day number (e.g., 15th)

You can pause a running campaign and resume later.

---

## Media Attachments

- **Supported**: JPG, PNG, GIF (images), PDF (document)
- **Max size**: 5MB
- The media must be publicly accessible to WhatsApp's servers. We host it on our CDN; you don't need to provide a URL.

Upload an image when creating the campaign (Image type). We'll host it and send it as a WhatsApp image message.

---

## Webhooks (Advanced)

If you have your own system, you can receive notifications when campaigns complete or when messages are delivered.

In **Settings** → **Integrations**, you can set a Webhook URL. We'll POST events to it:

```json
{
  "event": "campaign.completed",
  "campaign_id": "...",
  "total": 100,
  "delivered": 98,
  "failed": 2
}
```

Contact support to enable this feature (available on Business plan).

---

## Billing

### Upgrade

1. Go to **Billing** → **Plans**
2. Compare features and click **Upgrade** on your desired plan
3. You'll be redirected to Stripe Checkout, enter payment details
4. After payment, your limits increase immediately

### Payment Methods

We accept all major credit cards via Stripe. In some regions, we also support PayPal.

### Invoices

In **Billing** → **Invoices**, you can download past invoices as PDF.

### Cancel Subscription

If you want to downgrade or cancel:

- Go to **Billing** → **Subscription**
- Click **Cancel Subscription**
- You can choose to cancel immediately or at period end (you keep access until end of paid month)

After cancellation, you'll revert to Free plan at next billing cycle.

---

## Session Health

Your WhatsApp sessions can disconnect if:
- Your phone goes offline
- You log out of WhatsApp on your phone
- WhatsApp bans the number (rare but possible)

We'll email you if a session disconnects. You can also see status in **Sessions** page.

To fix:
1. Open WhatsApp on your phone
2. Go to Linked Devices
3. You should see our session listed; if it shows "Expired", you need to scan a new QR code:
   - In the platform, click **Reconnect** on that session (or delete + add new)
   - Scan the new QR code

If your number gets banned, you'll need to use a different phone number. WhatsApp bans are permanent for that number.

---

## Privacy & Data

- Your contacts' phone numbers are stored encrypted in our database.
- We only use them to send campaigns you create.
- We never share your data with third parties (except Stripe for billing, and our email service provider).
- You can delete your account anytime in Settings → Delete Account. This erases all your data.

See our full Privacy Policy for details.

---

## Safety & Compliance

**Do NOT use this service for:**
- Sending spam or unsolicited messages
- Harmful or illegal content
- Harassment or threats
- Misrepresentation

Violations will get your account banned.

WhatsApp has its own Terms of Service. Using unofficial automation tools carries a risk of number bans. Use responsibly and only message people who expect to hear from you.

---

## Getting Help

- **Documentation**: This guide
- **FAQ**: See below
- **Support**: Email support@yourdomain.com (Pro/Business) or use the in-app contact form (Free users have 24h response time)

---

## FAQ

**Q: Can I schedule messages to different time zones?**  
A: Yes. When you create a campaign, you set the time in your own timezone (from your profile). We convert to UTC on our server. Recipients receive at that moment globally.

**Q: What happens if I hit my message limit mid-campaign?**  
A: Campaign stops once limit reached. You'll get an email warning at 80% usage. Upgrade to send remaining contacts.

**Q: Do I need to keep my phone with me?**  
A: Your phone just needs to be online and have WhatsApp installed. It doesn't need to be on the same network. But if your phone is turned off or loses internet, the session will disconnect and messages won't send. Keep it connected.

**Q: Can I send messages to numbers not in my contacts?**  
A: Yes, but be careful. WhatsApp may flag messaging to unknown numbers as spam, especially in bulk. Use only with consent.

**Q: How do I stop a campaign that's currently running?**  
A: Pause it from the campaign detail page. Or you can delete the campaign (stops further sends but already sent messages remain).

**Q: Are my media files stored forever?**  
A: Media is stored for 30 days then automatically deleted. Campaigns keep a reference but actual file may be gone. If you need it longer, re-upload.

**Q: Can I use emojis?**  
A: Yes! All Unicode emojis are supported.

**Q: What if a message fails to deliver?**  
A: We retry once. If it still fails, we mark it as failed and continue with next contact. Common reasons: invalid number, number blocked, rate limit, or session disconnected.

**Q: Do you support WhatsApp Business API features like templates?**  
A: Not yet. We use unofficial OpenWA which supports personal accounts. Business features are not available. We may add support in future depending on demand.

---

## Pro Tips

1. **Warm up new numbers**: If you just bought a new SIM, start small (10-20 msgs/day) and gradually increase to avoid bans.
2. **Use variables**: `{name}` personalizes messages and reduces spam score.
3. **Tag your contacts**: Easier to segment campaigns (e.g., "last purchased >30 days").
4. **Schedule during waking hours**: Avoid late-night sends. Consider your recipients' timezone.
5. **Test first**: Always send a test to yourself before blasting 1000 contacts.

---

Happy scheduling! 🚀