@moltflow/skills 1.3.0 → 2.0.0

package/moltflow-leads/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: moltflow-leads
+description: "WhatsApp lead detection and CRM pipeline. Auto-detect purchase intent in groups, track lead status, bulk operations, CSV/JSON export. Use when: leads, lead detection, pipeline, qualify, convert, bulk status, export leads."
+source: "MoltFlow Team"
+version: "2.0.0"
+risk: safe
+requiredEnv:
+  - MOLTFLOW_API_KEY
+primaryEnv: MOLTFLOW_API_KEY
+disableModelInvocation: true
+---
+
+> **MoltFlow** -- WhatsApp Business automation for teams. Connect, monitor, and automate WhatsApp at scale.
+> [Save up to 17% with yearly billing](https://molt.waiflow.app/checkout?plan=free) -- Free tier available, no credit card required.
+
+# MoltFlow Leads -- Detection & CRM Pipeline
+
+Auto-detect purchase-intent leads from monitored WhatsApp groups, track them through a sales pipeline, perform bulk operations, and export for your CRM.
+
+## When to Use
+
+- "List leads" or "show detected leads"
+- "Update lead status" or "mark lead as contacted"
+- "Bulk update leads" or "change status for multiple leads"
+- "Add leads to group" or "bulk add to custom group"
+- "Export leads as CSV" or "download leads JSON"
+- "Check lead reciprocity" or "has this lead messaged me?"
+- "Filter leads by status" or "search leads"
+
+## Prerequisites
+
+1. **MOLTFLOW_API_KEY** -- Generate from the [MoltFlow Dashboard](https://molt.waiflow.app) under Settings > API Keys
+2. At least one monitored WhatsApp group with keyword detection enabled
+3. Base URL: `https://apiv2.waiflow.app/api/v2`
+
+## Authentication
+
+Every request must include one of:
+
+```
+Authorization: Bearer <jwt_token>
+```
+
+or
+
+```
+X-API-Key: <your_api_key>
+```
+
+---
+
+## How Lead Detection Works
+
+1. You monitor WhatsApp groups via the Groups API (see `moltflow` skill)
+2. Set `monitor_mode: "keywords"` with keywords like `"looking for"`, `"price"`, `"interested"`
+3. When a group member sends a message matching your keywords, MoltFlow auto-creates a lead
+4. Leads appear in the Leads API with status `new` and the triggering keyword highlighted
+5. You track them through the pipeline: `new` -> `contacted` -> `qualified` -> `converted`
+
+---
+
+## Leads API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/leads` | List leads (filter by status, group, search) |
+| GET | `/leads/{id}` | Get lead details |
+| PATCH | `/leads/{id}/status` | Update lead status (state machine validated) |
+| GET | `/leads/{id}/reciprocity` | Check if lead messaged you first (anti-spam) |
+| POST | `/leads/bulk/status` | Bulk update lead status |
+| POST | `/leads/bulk/add-to-group` | Bulk add leads to custom group |
+| GET | `/leads/export/csv` | Export as CSV (Pro+ plan, max 10,000) |
+| GET | `/leads/export/json` | Export as JSON (Pro+ plan, max 10,000) |
+
+### List Leads
+
+**GET** `/leads`
+
+Query parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `status` | string | Filter by status (`new`, `contacted`, `qualified`, `converted`, `lost`) |
+| `source_group_id` | UUID | Filter by source monitored group |
+| `search` | string | Search in contact name, phone, or keyword |
+| `limit` | int | Page size (default 50) |
+| `offset` | int | Pagination offset |
+
+**Response** `200 OK`:
+
+```json
+{
+  "leads": [
+    {
+      "id": "lead-uuid-...",
+      "contact_phone": "+15550123456",
+      "contact_name": "John D.",
+      "lead_status": "new",
+      "lead_score": 0,
+      "lead_detected_at": "2026-02-12T14:30:00Z",
+      "source_group": {
+        "id": "group-uuid-...",
+        "name": "Real Estate IL"
+      },
+      "trigger": {
+        "matched_keyword": "interested in buying",
+        "message_preview": "Hi, I'm interested in buying a 3-bedroom...",
+        "monitor_mode": "keywords",
+        "detected_at": "2026-02-12T14:30:00Z"
+      }
+    }
+  ],
+  "total": 47,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+### Get Lead Details
+
+**GET** `/leads/{id}`
+
+Returns full lead info including group context, detection metadata, message count, and status.
+
+### Update Lead Status
+
+**PATCH** `/leads/{id}/status`
+
+```json
+{
+  "status": "contacted"
+}
+```
+
+**State machine validation** -- only valid transitions are allowed:
+
+- `new` -> `contacted`, `qualified`, `converted`, `lost`
+- `contacted` -> `qualified`, `converted`, `lost`
+- `qualified` -> `converted`, `lost`
+- `converted` -> (terminal -- no further transitions)
+- `lost` -> `new` (reopen only)
+
+Invalid transitions return `400 Bad Request`.
+
+### Reciprocity Check
+
+**GET** `/leads/{id}/reciprocity?session_id=session-uuid`
+
+The `session_id` query parameter is **required** -- it specifies which WhatsApp session to check inbound messages from.
+
+```json
+{
+  "lead_id": "lead-uuid-...",
+  "has_messaged_first": true,
+  "last_inbound_at": "2026-02-12T15:00:00Z"
+}
+```
+
+Use this before reaching out -- if the lead hasn't messaged you directly, sending a cold message may trigger WhatsApp spam detection.
+
+### Bulk Status Update
+
+**POST** `/leads/bulk/status`
+
+```json
+{
+  "lead_ids": ["uuid1", "uuid2", "uuid3"],
+  "status": "contacted"
+}
+```
+
+**Response** `200 OK`:
+
+```json
+{
+  "updated": 3,
+  "failed": 0,
+  "errors": []
+}
+```
+
+Each lead is individually validated against the state machine. Leads with invalid transitions are reported in `errors` but don't block the rest.
+
+### Bulk Add to Custom Group
+
+**POST** `/leads/bulk/add-to-group`
+
+```json
+{
+  "lead_ids": ["uuid1", "uuid2"],
+  "custom_group_id": "custom-group-uuid-..."
+}
+```
+
+Adds leads' phone numbers to the specified custom group for use with Bulk Send or Scheduled Messages.
+
+### Export Leads
+
+**GET** `/leads/export/csv` -- Returns CSV file download
+**GET** `/leads/export/json` -- Returns JSON array
+
+Both support optional filters: `status`, `source_group_id`, `search`. Max 10,000 rows per export.
+
+**Requires Pro plan or above.**
+
+---
+
+## Examples
+
+### Full workflow: Detect -> Qualify -> Outreach
+
+```bash
+# 1. List new leads from a specific group
+curl "https://apiv2.waiflow.app/api/v2/leads?status=new&source_group_id=group-uuid" \
+  -H "X-API-Key: $MOLTFLOW_API_KEY"
+
+# 2. Check reciprocity before reaching out
+curl "https://apiv2.waiflow.app/api/v2/leads/{lead_id}/reciprocity?session_id=session-uuid" \
+  -H "X-API-Key: $MOLTFLOW_API_KEY"
+
+# 3. Update status to contacted
+curl -X PATCH https://apiv2.waiflow.app/api/v2/leads/{lead_id}/status \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "contacted"}'
+
+# 4. Bulk add qualified leads to a custom group for follow-up
+curl -X POST https://apiv2.waiflow.app/api/v2/leads/bulk/add-to-group \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "lead_ids": ["uuid1", "uuid2", "uuid3"],
+    "custom_group_id": "follow-up-group-uuid"
+  }'
+
+# 5. Export all converted leads as CSV
+curl "https://apiv2.waiflow.app/api/v2/leads/export/csv?status=converted" \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -o converted-leads.csv
+```
+
+---
+
+## Plan Requirements
+
+| Feature | Free | Starter | Pro | Business |
+|---------|------|---------|-----|----------|
+| Lead detection | Yes (2 groups) | Yes (5 groups) | Yes (20 groups) | Yes (100 groups) |
+| Lead list & detail | Yes | Yes | Yes | Yes |
+| Status update | Yes | Yes | Yes | Yes |
+| Bulk operations | -- | -- | Yes | Yes |
+| CSV/JSON export | -- | -- | Yes | Yes |
+
+---
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Invalid status transition or bad request |
+| 401 | Unauthorized (missing or invalid auth) |
+| 403 | Forbidden (plan limit or feature gate) |
+| 404 | Lead not found |
+| 429 | Rate limited |
+
+---
+
+## Related Skills
+
+- **moltflow** -- Core API: sessions, messaging, groups, labels, webhooks
+- **moltflow-outreach** -- Bulk Send, Scheduled Messages, Custom Groups
+- **moltflow-ai** -- AI-powered auto-replies, voice transcription, RAG, style profiles
+- **moltflow-a2a** -- Agent-to-Agent protocol, encrypted messaging, content policy
+- **moltflow-reviews** -- Review collection and testimonial management
+- **moltflow-admin** -- Platform administration, user management, plan configuration

package/moltflow-outreach/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: moltflow-outreach
+description: "Bulk messaging, scheduled messages, and custom groups for WhatsApp outreach. Use when: bulk send, broadcast, schedule message, cron, custom group, contact list, ban-safe messaging."
+source: "MoltFlow Team"
+version: "2.0.0"
+risk: safe
+requiredEnv:
+  - MOLTFLOW_API_KEY
+primaryEnv: MOLTFLOW_API_KEY
+disableModelInvocation: true
+---
+
+> **MoltFlow** -- WhatsApp Business automation for teams. Connect, monitor, and automate WhatsApp at scale.
+> [Save up to 17% with yearly billing](https://molt.waiflow.app/checkout?plan=free) -- Free tier available, no credit card required.
+
+# MoltFlow Outreach -- Bulk Send, Scheduled Messages & Custom Groups
+
+Broadcast to custom contact lists with ban-safe throttling, schedule recurring messages with timezone support, and manage targeted contact groups for WhatsApp outreach.
+
+## When to Use
+
+- "Send bulk message" or "broadcast to group"
+- "Schedule a WhatsApp message" or "set up recurring message"
+- "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`
+
+## 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/{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.
+
+**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-messages`
+
+```json
+{
+  "name": "Follow-up",
+  "session_id": "session-uuid-...",
+  "custom_group_id": "custom-group-uuid-...",
+  "schedule_type": "one_time",
+  "message_content": "Just checking in on your order!",
+  "scheduled_time": "2026-02-15T09:00:00",
+  "timezone": "Asia/Jerusalem"
+}
+```
+
+### Create Recurring Schedule (Cron)
+
+**POST** `/scheduled-messages`
+
+```json
+{
+  "name": "Weekly Update",
+  "session_id": "session-uuid-...",
+  "custom_group_id": "custom-group-uuid-...",
+  "schedule_type": "cron",
+  "message_content": "Weekly team report is ready!",
+  "cron_expression": "0 9 * * MON",
+  "timezone": "America/New_York"
+}
+```
+
+**Response** `201 Created`:
+
+```json
+{
+  "id": "schedule-uuid-...",
+  "name": "Weekly Update",
+  "status": "active",
+  "schedule_type": "cron",
+  "cron_expression": "0 9 * * MON",
+  "timezone": "America/New_York",
+  "next_run_at": "2026-02-17T09:00:00-05:00",
+  "created_at": "2026-02-12T10:00:00Z"
+}
+```
+
+### Schedule Types
+
+- `one_time` -- Single send at `scheduled_time`
+- `daily` -- Every day (requires `cron_expression`)
+- `weekly` -- Every week (requires `cron_expression`)
+- `monthly` -- Every month (requires `cron_expression`)
+- `cron` -- Custom cron expression (e.g., `0 9 * * MON-FRI`)
+
+**Note:** All recurring types (`daily`, `weekly`, `monthly`, `cron`) require a `cron_expression`. Minimum interval: 5 minutes.
+
+### Required Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Schedule name (1-255 chars) |
+| `session_id` | UUID | Yes | WhatsApp session to send from |
+| `custom_group_id` | UUID | Yes | Target custom group |
+| `schedule_type` | string | Yes | One of: `one_time`, `daily`, `weekly`, `monthly`, `cron` |
+| `message_type` | string | No | `text` (default) or `media` |
+| `message_content` | string | Conditional | Message text (max 4096). Required if no `media_url` |
+| `media_url` | string | Conditional | HTTP(S) URL. Required if no `message_content` |
+| `scheduled_time` | datetime | Conditional | ISO 8601. Required for `one_time` |
+| `cron_expression` | string | Conditional | Cron string. Required for recurring types |
+| `timezone` | string | No | IANA timezone (default: `UTC`) |
+
+### Schedule Status Values
+
+`active` -> `paused` / `cancelled` / `completed`
+
+---
+
+## Examples
+
+### Full workflow: Group -> Bulk Send -> Schedule
+
+```bash
+# 1. Create a custom group
+curl -X POST https://apiv2.waiflow.app/api/v2/custom-groups \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "VIP Clients"}'
+
+# 2. Add members to the group
+curl -X POST https://apiv2.waiflow.app/api/v2/custom-groups/{group_id}/members/add \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"contacts": [{"phone": "+15550123456"}, {"phone": "+15550987654"}, {"phone": "+15551112222"}]}'
+
+# 3. Bulk send to the group
+curl -X POST https://apiv2.waiflow.app/api/v2/bulk-send \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "session-uuid-...",
+    "custom_group_id": "group-uuid-...",
+    "message_content": "Exclusive offer for our VIP clients!"
+  }'
+
+# 4. Schedule a weekly follow-up to the group
+curl -X POST https://apiv2.waiflow.app/api/v2/scheduled-messages \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Weekly VIP Update",
+    "session_id": "session-uuid-...",
+    "custom_group_id": "group-uuid-...",
+    "schedule_type": "cron",
+    "message_content": "Weekly report is ready!",
+    "cron_expression": "0 9 * * MON",
+    "timezone": "Asia/Jerusalem"
+  }'
+```
+
+### Pause and resume a bulk send
+
+```bash
+# Pause
+curl -X POST https://apiv2.waiflow.app/api/v2/bulk-send/{job_id}/pause \
+  -H "X-API-Key: $MOLTFLOW_API_KEY"
+
+# Resume
+curl -X POST https://apiv2.waiflow.app/api/v2/bulk-send/{job_id}/resume \
+  -H "X-API-Key: $MOLTFLOW_API_KEY"
+```
+
+### Export group members
+
+```bash
+curl https://apiv2.waiflow.app/api/v2/custom-groups/{group_id}/export/csv \
+  -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -o vip-clients.csv
+```
+
+---
+
+## Plan Limits
+
+| Feature | Free | Starter | Pro | Business |
+|---------|------|---------|-----|----------|
+| Custom Groups | 2 | 5 | 20 | 100 |
+| Bulk Send | -- | Yes | Yes | Yes |
+| Scheduled Messages | -- | Yes | Yes | Yes |
+| Messages/month | 50 | 500 | 1,500 | 3,000 |
+
+---
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Bad request (invalid input) |
+| 401 | Unauthorized (missing or invalid auth) |
+| 403 | Forbidden (plan limit or feature gate) |
+| 404 | Resource not found |
+| 422 | Validation error (missing required fields) |
+| 429 | Rate limited |
+
+---
+
+## Related Skills
+
+- **moltflow** -- Core API: sessions, messaging, groups, labels, webhooks
+- **moltflow-leads** -- Lead detection, pipeline tracking, bulk operations, CSV/JSON export
+- **moltflow-ai** -- AI-powered auto-replies, voice transcription, RAG, style profiles
+- **moltflow-a2a** -- Agent-to-Agent protocol, encrypted messaging, content policy
+- **moltflow-reviews** -- Review collection and testimonial management
+- **moltflow-admin** -- Platform administration, user management, plan configuration