moltflow-outreach

Bulk messaging, scheduled messages, scheduled reports, and custom groups for WhatsApp outreach. Use when: bulk send, broadcast, schedule message, schedule report, cron, custom group, contact list, ban-safe messaging.

> **MoltFlow** -- WhatsApp Business automation for teams. Connect, monitor, and automate WhatsApp at scale.
> ***Due to high demand and a recent registration issue, we're offering our top-tier Business plan with unlimited quotas for just $19.90/month on yearly billing — for a limited time only.*** [**Claim the deal**](https://buy.stripe.com/cNifZibX7gpQebJ0nsfnO00)
> Free tier available. [Sign up](https://molt.waiflow.app/checkout?plan=free)

# MoltFlow Outreach -- Bulk Send, Scheduled Messages, Reports & Custom Groups

Broadcast to custom contact lists with ban-safe throttling, schedule recurring messages with timezone support, generate automated reports with WhatsApp delivery, and manage targeted contact groups for WhatsApp outreach.

## Real-World Scenarios

**Gym owner** — "Send a 'Happy New Year' promo with a discount code to all my members, spaced out so I don't get banned."

**Freelance consultant** — "Every Friday at 5 PM, send a 'weekend availability' message to my active client list."

**Marketing agency** — "Build a contact group from 3 WhatsApp groups, deduplicate, and blast a product launch announcement."

**Restaurant chain** — "Schedule a weekly report showing how many reservation confirmations were sent and delivered — send it to my WhatsApp every Monday morning."

## When to Use

- "Send bulk message" or "broadcast to group"
- "Schedule a WhatsApp message" or "set up recurring message"
- "Generate a report" or "schedule a report"
- "Send me a usage summary" or "get a lead pipeline report"
- "Create a contact list" or "build custom group"
- "Pause bulk send" or "cancel scheduled message"
- "Export group members as CSV" or "import contacts"
- "Send weekly update" or "set up cron schedule"

## Prerequisites

1. **MOLTFLOW_API_KEY** -- Generate from the [MoltFlow Dashboard](https://molt.waiflow.app) under Settings > API Keys
2. At least one connected WhatsApp session (status: `working`)
3. Base URL: `https://apiv2.waiflow.app/api/v2`

## Required API Key Scopes

| Scope | Access |
|-------|--------|
| `custom-groups` | `read/manage` |
| `bulk-send` | `read/manage` |
| `scheduled` | `read/manage` |
| `reports` | `read/manage` |

## Authentication

Every request must include one of:

```
Authorization: Bearer <jwt_token>
```

or

```
X-API-Key: <your_api_key>
```

---

## Custom Groups

Build targeted contact lists for Bulk Send and Scheduled Messages. Custom Groups are MoltFlow contact lists -- not WhatsApp groups.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/custom-groups` | List all custom groups |
| POST | `/custom-groups` | Create group (with optional initial members) |
| GET | `/custom-groups/contacts` | List all unique contacts across sessions |
| GET | `/custom-groups/wa-groups` | List WhatsApp groups for import |
| POST | `/custom-groups/from-wa-groups` | Create group by importing WA group members |
| GET | `/custom-groups/{id}` | Group details with members |
| PATCH | `/custom-groups/{id}` | Update group name |
| DELETE | `/custom-groups/{id}` | Delete group and members |
| POST | `/custom-groups/{id}/members/add` | Add members (skips duplicates) |
| POST | `/custom-groups/{id}/members/remove` | Remove members by phone |
| GET | `/custom-groups/{id}/export/csv` | Export members as CSV |
| GET | `/custom-groups/{id}/export/json` | Export members as JSON |

### Create Custom Group

**POST** `/custom-groups`

```json
{
  "name": "VIP Clients",
  "members": [
    {"phone": "+15550123456"},
    {"phone": "+15550987654", "name": "Jane Doe"}
  ]
}
```

Members is an array of objects with `phone` (required) and `name` (optional). Omit `members` to create an empty group.

### Create Group from WhatsApp Groups

**POST** `/custom-groups/from-wa-groups`

```json
{
  "name": "Imported Leads",
  "wa_groups": [
    {"wa_group_id": "120363012345@g.us", "session_id": "session-uuid-..."},
    {"wa_group_id": "120363067890@g.us", "session_id": "session-uuid-..."}
  ]
}
```

Resolves participants from each WhatsApp group, deduplicates by phone number, and creates the custom group with all unique members.

### List WhatsApp Groups

**GET** `/custom-groups/wa-groups`

Returns all WhatsApp groups across your connected sessions with participant counts. Use this to discover groups available for import.

**Response** `201 Created`:

```json
{
  "id": "group-uuid-...",
  "name": "VIP Clients",
  "member_count": 2,
  "created_at": "2026-02-12T10:00:00Z"
}
```

### Add Members

**POST** `/custom-groups/{id}/members/add`

```json
{
  "contacts": [
    {"phone": "+15551112222"},
    {"phone": "+15553334444", "name": "Bob Smith"}
  ]
}
```

Each contact is an object with `phone` (required) and `name` (optional). Max 1,000 per request. Duplicates are silently skipped.

### Export Members

**GET** `/custom-groups/{id}/export/csv` -- Returns CSV download
**GET** `/custom-groups/{id}/export/json` -- Returns JSON array

---

## Bulk Send

Broadcast messages to a custom group with ban-safe throttling. Random 30s-2min delays between messages simulate human behavior.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/bulk-send` | Create bulk send job (quota reserved) |
| GET | `/bulk-send` | List all bulk send jobs |
| GET | `/bulk-send/{id}` | Job details with recipients |
| POST | `/bulk-send/{id}/pause` | Pause running job |
| POST | `/bulk-send/{id}/resume` | Resume paused job |
| POST | `/bulk-send/{id}/cancel` | Cancel job (releases unused quota) |
| GET | `/bulk-send/{id}/progress` | Real-time progress via SSE |

### Create Bulk Send Job

**POST** `/bulk-send`

```json
{
  "session_id": "session-uuid-...",
  "custom_group_id": "custom-group-uuid-...",
  "message_content": "Special offer for our VIP clients!"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `session_id` | UUID | Yes | WhatsApp session to send from |
| `custom_group_id` | UUID | Yes | Target custom group |
| `message_type` | string | No | `text` (default) or `media` |
| `message_content` | string | Conditional | Message text (max 4096 chars). Required if no `media_url` |
| `media_url` | string | Conditional | HTTP(S) URL for media. Required if no `message_content` |

**Response** `201 Created`:

```json
{
  "id": "job-uuid-...",
  "session_id": "session-uuid-...",
  "custom_group_id": "custom-group-uuid-...",
  "status": "running",
  "total_recipients": 127,
  "sent_count": 0,
  "failed_count": 0,
  "created_at": "2026-02-12T10:00:00Z"
}
```

### Stream Progress (SSE)

**GET** `/bulk-send/{id}/progress`

Returns Server-Sent Events with real-time updates:

```
data: {"sent": 45, "total": 127, "failed": 0, "status": "running"}
data: {"sent": 46, "total": 127, "failed": 0, "status": "running"}
```

### Job Status Values

`pending` -> `running` -> `completed` / `paused` / `cancelled` / `failed`

### Anti-Ban Safety

- Random 30s-2min delays between messages
- Typing simulation before each message
- Seen/read indicators marked automatically
- Burst rate limiting (4 msgs/2 min)

---

## Scheduled Messages

Schedule one-time or recurring WhatsApp messages to custom groups with timezone support and full lifecycle control.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/scheduled-messages` | List all scheduled messages |
| POST | `/scheduled-messages` | Create schedule (one-time or recurring) |
| GET | `/scheduled-messages/{id}` | Schedule details with execution history |
| PATCH | `/scheduled-messages/{id}` | Update schedule and recalculate next run |
| POST | `/scheduled-messages/{id}/cancel` | Cancel schedule |
| POST | `/scheduled-messages/{id}/pause` | Pause active schedule |
| POST | `/scheduled-messages/{id}/resume` | Resume paused schedule |
| DELETE | `/scheduled-messages/{id}` | Delete cancelled/completed schedule |
| GET | `/scheduled-messages/{id}/history` | Execution history (paginated) |

### Create One-Time Schedule

**POST** `/scheduled-mess