moltflow-ai

AI-powered WhatsApp features: auto-replies, voice transcription, RAG knowledge base, and style profiles. Use when: ai reply, transcribe voice, knowledge base, upload document, build style, learn mode.

> **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 AI Features

AI-powered capabilities for WhatsApp automation: voice transcription, RAG knowledge base, style profile learning, and intelligent reply generation.

## Real-World Scenarios

**Healthcare clinic** — "Transcribe patient voice notes sent via WhatsApp and save them as searchable text records I can pull up later."

**Law firm** — "Upload our service agreements to the knowledge base so the AI can answer client questions about terms and pricing accurately."

**Sales team** — "Clone my top closer's writing style so AI replies to leads sound like him — casual, confident, uses emojis."

**Customer support** — "Auto-reply to common questions like 'What are your hours?' and 'Where are you located?' using our FAQ document."

## When to Use

- "Transcribe a voice message" or "convert audio to text"
- "Upload a document to knowledge base" or "ingest PDF"
- "Search knowledge base" or "find in documents"
- "Build style profile" or "learn my writing style"
- "Generate an AI reply" or "auto-reply to customer"
- "Preview AI response" or "test reply generation"
- "List knowledge sources" or "delete document"

## Prerequisites

1. **MOLTFLOW_API_KEY** -- Generate from the [MoltFlow Dashboard](https://molt.waiflow.app) under Settings > API Keys
2. **Pro plan or higher** ($29.90/mo) -- AI features are not available on the Starter plan
3. Base URL: `https://apiv2.waiflow.app/api/v2`
4. All AI endpoints are under the `/ai` prefix

## Required API Key Scopes

| Scope | Access |
|-------|--------|
| `ai` | `read/manage` |

## Authentication

Every request must include one of:

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

or

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

---

## Voice Transcription

Transcribe WhatsApp voice messages using Whisper AI. Transcription runs asynchronously via a Celery worker.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/ai/voice/transcribe` | Queue a voice message for transcription |
| GET | `/ai/voice/status/{task_id}` | Check transcription task status |
| GET | `/ai/messages/{message_id}/transcript` | Get the transcript for a message |

### Queue Transcription

**POST** `/ai/voice/transcribe`

```json
{
  "message_id": "msg-uuid-..."
}
```

**Response** `200 OK`:

```json
{
  "task_id": "celery-task-id-...",
  "message_id": "msg-uuid-...",
  "status": "queued"
}
```

### Check Status

**GET** `/ai/voice/status/{task_id}`

```json
{
  "task_id": "celery-task-id-...",
  "status": "completed",
  "result": {
    "transcript": "Hello, I wanted to ask about...",
    "language": "en",
    "confidence": 0.95
  }
}
```

Status values: `queued`, `processing`, `completed`, `failed`

### Get Transcript

**GET** `/ai/messages/{message_id}/transcript`

```json
{
  "message_id": "msg-uuid-...",
  "transcript": "Hello, I wanted to ask about...",
  "language": "en",
  "confidence": 0.95,
  "transcribed_at": "2026-02-11T10:05:00Z"
}
```

---

## RAG Knowledge Base

Build a searchable knowledge base for AI-powered replies grounded in your business data.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/ai/knowledge/ingest` | Upload and index a document |
| POST | `/ai/knowledge/search` | Semantic search across documents |
| GET | `/ai/knowledge/sources` | List all indexed documents |
| DELETE | `/ai/knowledge/{source_id}` | Delete a document |

### Upload Document

**POST** `/ai/knowledge/ingest` (multipart/form-data)

| Field | Type | Description |
|-------|------|-------------|
| `file` | File | PDF or TXT file (max 100MB) |

**Response** `200 OK`:

```json
{
  "id": "src-uuid-...",
  "name": "product-catalog.pdf",
  "source_type": "application/pdf",
  "chunk_count": 47,
  "status": "indexed",
  "task_id": "celery-task-id-..."
}
```

Supported file types: `application/pdf`, `text/plain` (`.pdf`, `.txt`)

### Search Knowledge Base

**POST** `/ai/knowledge/search`

```json
{
  "query": "What is the return policy?",
  "top_k": 5
}
```

**Response** `200 OK`:

```json
{
  "query": "What is the return policy?",
  "results": [
    {
      "source_id": "src-uuid-...",
      "content_type": "application/pdf",
      "content_preview": "Our return policy allows returns within 30 days...",
      "metadata": {"page": 12, "chunk": 3},
      "similarity": 0.92
    }
  ],
  "count": 1
}
```

Optional filters:

```json
{
  "query": "shipping costs",
  "filters": {"source_type": "application/pdf"},
  "top_k": 10
}
```

### List Documents

**GET** `/ai/knowledge/sources`

```json
[
  {
    "id": "src-uuid-...",
    "name": "product-catalog.pdf",
    "source_type": "application/pdf",
    "chunk_count": 47,
    "status": "indexed",
    "created_at": "2026-02-11T09:00:00Z",
    "indexed_at": "2026-02-11T09:02:00Z"
  }
]
```

Document status values: `processing`, `indexed`, `failed`

### Delete Document

**DELETE** `/ai/knowledge/{source_id}` -- Returns `204 No Content`

---

## Style Profiles (Learn Mode)

Configure AI writing style profiles scoped to individual chats or as a general profile. The AI auto-selects the best matching profile when generating replies.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/ai/style/train` | Start building a style profile |
| GET | `/ai/style/status/{task_id}` | Check build status |
| GET | `/ai/style/profile` | Get a style profile |
| GET | `/ai/style/profiles` | List all style profiles |
| DELETE | `/ai/style/profile/{profile_id}` | Delete a style profile |

### Build Style Profile

**POST** `/ai/style/train`

```json
{
  "session_id": "session-uuid-...",
  "wa_chat_id": "5511999999999@c.us",
  "name": "Sales"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `contact_id` | string | No | Legacy — use `wa_chat_id` instead |
| `session_id` | UUID | No | Session to scope the build to |
| `wa_chat_id` | string | No | Chat to scope the build to (WhatsApp JID). Omit for general profile |
| `name` | string | No | Profile name (e.g., "Sales", "Support", "Family") |

**Note:** Omit both `session_id` and `wa_chat_id` to build a general profile from all conversations.

**Response** `200 OK`:

```json
{
  "task_id": "celery-task-id-...",
  "tenant_id": "tenant-uuid-...",
  "contact_id": "5511999999999@c.us",
  "status": "queued"
}
```

The build runs asynchronously. Check progress with the status endpoint.

### Get Style Profile

**GET** `/ai/style/profile?contact_id=5511999999999@c.us`

```json
{
  "id": "profile-uuid-...",
  "tenant_id": "tenant-uuid-...",
  "contact_id": "5511999999999@c.us",
  "name": "Sales",
  "session_id": "session-uuid-...",
  "wa_chat_id": "5511999999999@c.us",
  "features": {
    "avg_sentence_length": 12.5,
    "formality_score": 0.7,
    "emoji_frequency": 0.15,
    "vocabulary_richness": 0.82
  },
  "sample_count": 150,
  "last_trained_at": "2026-02-11T09:30:00Z"
}
```

### List All Profiles

**GET** `/ai/style/profiles`

```json
[
  {
    "id": "profile-uuid-1",
    "tenant_id": "tenant-uuid-...",
    "name": "Sales",
    "session_id": "session-uuid-...",
    "wa_chat_id": "5511999999999@c.us",
    "features": { "formality_score": 0.7 },
    "sample_count": 150,
    "last_trained_at": "2026-02-11T09:30:00Z"
  },
  {
    "id": "profile-uuid-2",
    "tenant_id": "tenant-uuid-...",
    "name": "General",
    "session_id": null,
    "wa_chat_id": null,
    "features": { "formality_score": 0.5 },
    "sample_count": 420,
    "last_trained_at": "2026-02-11T10:00:00Z"
  }
]
```

### Delete Profile

**DELETE** `/ai/style/profile/{profil