npm package: @moltflow/openai-actions
Description: OpenAPI specs for MoltFlow WhatsApp Automation — use with Custom GPT Actions
Author: MoltFlow Team
Latest version: 2.0.0

# @moltflow/openai-actions — MoltFlow for Custom GPTs

Connect your MoltFlow WhatsApp automation to ChatGPT using Custom GPT Actions. Send messages, track leads, and manage campaigns through natural language.

## Overview

This package provides OpenAPI 3.1.0 specifications for the MoltFlow API, optimized for use with OpenAI Custom GPT Actions. It enables ChatGPT to interact with your WhatsApp automation platform through conversational commands.

**Features:**
- 📨 Send WhatsApp messages via natural language
- 📊 Track and manage leads from monitored groups
- 🚀 Create and control bulk send campaigns
- 📅 Schedule recurring messages
- 📈 Monitor usage and plan limits
- 🔐 Secure API key authentication

## Quick Start

### Prerequisites

- A MoltFlow account ([sign up here](https://molt.waiflow.app))
- An API key from [Settings → API Keys](https://molt.waiflow.app/settings/api-keys)
- ChatGPT Plus or Team subscription (required for Custom GPTs)

### Installation

**Option 1: Import from CDN (Recommended)**

Use the jsdelivr CDN URL directly in GPT Builder:
```
https://cdn.jsdelivr.net/npm/@moltflow/openai-actions@latest/openapi-simplified.yaml
```

**Option 2: Install via npm**

```bash
npm install @moltflow/openai-actions
```

Then import `node_modules/@moltflow/openai-actions/openapi-simplified.yaml` in GPT Builder.

## Setup in GPT Builder

Follow these steps to create your MoltFlow Custom GPT:

### Step 1: Create New GPT

1. Go to [ChatGPT](https://chat.openai.com)
2. Click your profile → **"My GPTs"**
3. Click **"Create a GPT"**

### Step 2: Configure GPT Details

In the **Configure** tab:

1. **Name**: `MoltFlow WhatsApp Assistant` (or your preferred name)
2. **Description**: `Manage WhatsApp automation — send messages, track leads, run campaigns`
3. **Instructions**: Paste this prompt:
   ```
   You are a WhatsApp automation assistant powered by MoltFlow. Help the user manage their WhatsApp sessions, send messages, track leads, and run outreach campaigns.

   Always confirm before sending messages or starting bulk sends. Provide clear status updates and next steps.

   When listing sessions, show the name, status, and phone number clearly.
   When displaying leads, include contact info, status, and score.
   For bulk send jobs, show progress (sent/total) and estimated completion.
   ```

4. **Conversation starters** (optional):
   - `List my WhatsApp sessions`
   - `Send a message via WhatsApp`
   - `Show me new leads from this week`
   - `Create a bulk send campaign`

5. **Capabilities**: Disable all (Web Browsing, DALL·E, Code Interpreter)

### Step 3: Add Actions

1. Scroll to **Actions** section
2. Click **"Create new action"**
3. **Import from URL** → Paste:
   ```
   https://cdn.jsdelivr.net/npm/@moltflow/openai-actions@latest/openapi-simplified.yaml
   ```
   OR **Import from file** → Upload `openapi-simplified.yaml`

4. The schema will load automatically

### Step 4: Configure Authentication

1. In the **Authentication** section, select **"API Key"**
2. Configure:
   - **Authentication Type**: `API Key`
   - **API Key**: Paste your MoltFlow API key
   - **Auth Type**: `Custom`
   - **Custom Header Name**: `X-API-Key`

3. Click **Save**

### Step 5: Test Your GPT

1. Switch to **Preview** tab
2. Try these test commands:
   - `"List my sessions"`
   - `"What's my current usage?"`
   - `"Show me leads with status new"`

3. If you see API responses, you're ready to go!

### Step 6: Publish (Optional)

- **Only me**: Keep it private
- **Anyone with link**: Share with your team
- **Public**: List in GPT Store

## Authentication

MoltFlow uses API key authentication via the `X-API-Key` header.

### Getting Your API Key

1. Log in to [MoltFlow Dashboard](https://molt.waiflow.app)
2. Go to **Settings** → **API Keys**
3. Click **"Create API Key"**
4. Copy the key immediately (it won't be shown again)

### API Key Scopes

For full GPT functionality, your API key needs these scopes:
- `sessions:read` — View WhatsApp sessions
- `messages:send` — Send messages
- `messages:read` — View chat history
- `leads:read` — View leads
- `leads:manage` — Update lead status
- `custom-groups:read` — View contact groups
- `custom-groups:manage` — Create/edit groups
- `bulk-send:read` — View bulk send jobs
- `bulk-send:manage` — Create/control campaigns
- `usage:read` — View usage stats

Or use `["*"]` for full access.

## Available Endpoints

### Sessions
- `GET /sessions` — List all WhatsApp sessions
- `POST /sessions` — Create new session
- `GET /sessions/{id}` — Get session details
- `POST /sessions/{id}/start` — Start session and generate QR
- `GET /sessions/{id}/qr` — Get QR code for pairing

### Messages
- `POST /messages/send` — Send WhatsApp message
- `GET /messages/chats` — List all chats
- `GET /messages/chats/{id}/messages` — Get chat message history

### Leads
- `GET /leads` — List detected leads
- `PATCH /leads/{id}/status` — Update lead status

### Custom Groups
- `GET /custom-groups` — List contact groups
- `POST /custom-groups` — Create new group
- `POST /custom-groups/{id}/members/add` — Add contacts to group

### Bulk Send
- `GET /bulk-send` — List bulk send jobs
- `POST /bulk-send` — Create bulk send campaign
- `GET /bulk-send/{id}` — Get job status
- `POST /bulk-send/{id}/pause` — Pause job
- `POST /bulk-send/{id}/resume` — Resume job

### Usage
- `GET /usage` — Get current usage and limits

## Simplified vs Full Spec

This package includes two OpenAPI specs:

| Spec | Size | Endpoints | Use Case |
|------|------|-----------|----------|
| `openapi-simplified.yaml` | ~16KB | 20 most common | **Recommended** for GPT Actions (fits easily within 100K limit) |
| `openapi.yaml` | ~53KB | 30+ comprehensive | Full API documentation, tools, advanced integrations |

**For Custom GPTs, use the simplified spec.** It covers 90% of use cases and loads faster.

## Example Usage

Once configured, interact with your MoltFlow GPT naturally:

### Sending Messages
```
"Send a message to +1-555-0123 saying 'Thanks for your interest!'"
```

### Managing Leads
```
"Show me all leads with status 'new' from the last 7 days"
"Update lead abc-123 to status 'contacted'"
```

### Bulk Campaigns
```
"Create a bulk send to group 'Newsletter Subscribers' with message: Welcome to our community!"
"What's the status of bulk send job xyz-789?"
```

### Session Management
```
"List all my active WhatsApp sessions"
"Start session 'Business Line' and show me the QR code"
```

### Usage Tracking
```
"How many messages have I sent this month?"
"What's my message limit?"
```

## Troubleshooting

### Error: "Invalid or missing API key" (401)

**Cause**: API key not configured or incorrect

**Fix**:
1. Verify your API key at https://molt.waiflow.app/settings/api-keys
2. In GPT Builder → Actions → Authentication, paste the correct key
3. Ensure `X-API-Key` is the header name (case-sensitive)

### Error: "Rate limit exceeded" (429)

**Cause**: Too many requests in short time

**Fix**:
- Wait 60 seconds before retrying
- Rate limits by plan:
  - Free: 10 requests/min
  - Starter: 20 requests/min
  - Pro: 40 requests/min
  - Business: 60 requests/min

### Error: "Message limit reached" (403)

**Cause**: Monthly message quota exceeded

**Fix**:
- Check usage: `"What's my current usage?"`
- Upgrade plan at https://molt.waiflow.app/settings/billing

### Schema Import Fails

**Cause**: Spec exceeds GPT Actions 100K character limit (unlikely with simplified spec)

**Fix**:
- Ensure you're using `openapi-simplified.yaml` (not `openapi.yaml`)
- Character count: `wc -c openapi-simplified.yaml` (should be ~16KB)

### Actions Not Showing in Preview

**Cause**: Authentication not configured

**Fix**:
1. Go to Actions section in GPT Builder
2. Verify Authentication is set to "API Key"
3. Ensure API key is pasted and saved
4. Refresh the preview

### "Session not found" errors

**Cause**: Session ID doesn't exist or belongs to another tenant

**Fix**:
- List sessions first: `"Show me my sessions"`
- Use the correct session UUID from the list
- Verify session belongs to your API key's tenant

## Support & Resources

- **Documentation**: https://molt.waiflow.app/docs
- **API Reference**: https://apiv2.waiflow.app/docs
- **Support**: support@waiflow.app
- **GitHub**: https://github.com/moltflow/moltflow
- **Community**: https://discord.gg/moltflow

## License

MIT License — see [LICENSE](LICENSE) for details.

## Related Packages

- **[@moltflow/mcp-server](https://www.npmjs.com/package/@moltflow/mcp-server)** — MCP server for Claude Desktop
- **[@moltflow/skills](https://www.npmjs.com/package/@moltflow/skills)** — ClawHub skill for OpenClaw AI agents

---

**Built with ❤️ by the MoltFlow team**