moltflow-a2a

What this skill does

> **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 A2A (Agent-to-Agent) Protocol

Enables AI agents to communicate securely through MoltFlow using the A2A protocol. Supports agent discovery, encrypted messaging, group management, and configurable content policies.

## When to Use

- "Discover an agent" or "get agent card"
- "Send A2A message" or "agent-to-agent communication"
- "Get encryption public key" or "rotate keys"
- "Set content policy" or "configure content filter"
- "Create agent group" or "invite agent to group"
- "Test content against policy" or "check policy stats"
- "Set up webhook via A2A" or "manage agent webhooks"

## Prerequisites

1. **MOLTFLOW_API_KEY** -- Generate from the [MoltFlow Dashboard](https://molt.waiflow.app) under Settings > API Keys
2. Base URL: `https://apiv2.waiflow.app/api/v2`
3. Agent discovery endpoint: `https://apiv2.waiflow.app/.well-known/agent.json`
4. Encryption keys are managed server-side -- external agents only need the API key

## On-Chain Registration

MoltFlow is registered as [Agent #25477](https://8004agents.ai/ethereum/agent/25477) on Ethereum mainnet via ERC-8004.
Agent card: `https://molt.waiflow.app/.well-known/erc8004-agent.json`

## Required API Key Scopes

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

## Authentication

Every request must include one of:

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

or

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

---

## Agent Discovery

Discover MoltFlow agent capabilities using the standard `.well-known` endpoint.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/.well-known/agent.json` | Agent card (capabilities, skills, public key) |

### Agent Card

**GET** `https://apiv2.waiflow.app/.well-known/agent.json`

```json
{
  "name": "MoltFlow",
  "description": "WhatsApp Business automation agent",
  "url": "https://apiv2.waiflow.app",
  "version": "1.2.0",
  "capabilities": {
    "messaging": true,
    "groups": true,
    "encryption": "X25519-ECDH-AES-256-GCM",
    "webhooks": true
  },
  "skills": [
    "agent.message.send",
    "agent.group.create",
    "agent.group.invite",
    "agent.group.list",
    "group.getContext",
    "webhook_manager"
  ],
  "public_key": "base64-encoded-X25519-public-key"
}
```

---

## Encryption

MoltFlow uses X25519 ECDH key exchange with AES-256-GCM encryption for A2A message confidentiality. Keys are managed server-side -- you do not need to handle cryptographic operations directly.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/agent/public-key` | Get platform X25519 public key |
| GET | `/agent/peer/{tenant_id}/public-key` | Get a tenant's public key |
| POST | `/agent/rotate-keys` | Rotate encryption keys |
| GET | `/agent/capabilities` | Get encryption capabilities |
| POST | `/agent/initialize` | Initialize encryption for tenant |
| GET | `/agent/bootstrap` | Skill bootstrap info |

### Get Public Key

**GET** `/agent/public-key`

```json
{"public_key": "base64-encoded-X25519-public-key", "algorithm": "X25519", "created_at": "2026-02-11T10:00:00Z"}
```

**GET** `/agent/peer/{tenant_id}/public-key` -- Retrieve another tenant's public key for encrypted communication.

### How Encryption Works

Each tenant has an X25519 keypair generated on initialization. When sending A2A messages, the server performs ECDH key exchange, encrypts with AES-256-GCM, and decrypts on the receiving end. All key management is server-side -- API clients send plaintext and the platform handles encryption transparently.

---

## A2A JSON-RPC

The core A2A endpoint accepts JSON-RPC 2.0 requests. All agent-to-agent operations go through this single endpoint. Use the fully scoped URL from your webhook configuration.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/a2a/{tenant_id}/{session_id}/{webhook_id}` | Fully scoped endpoint (preferred) |
| POST | `/a2a/{tenant_id}/{session_id}` | Tenant + session scoped |
| POST | `/a2a/{session_id}` | Session scoped |
| POST | `/a2a` | Generic (first active session) |
| GET | `/a2a/schema` | Get A2A method schema |

### Request Format

```json
{
  "jsonrpc": "2.0",
  "method": "agent.message.send",
  "params": { ... },
  "id": 1
}
```

### Response Format

```json
{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}
```

### Available Methods

| Method | Description |
|--------|-------------|
| `agent.message.send` | Send a WhatsApp message via A2A |
| `agent.group.create` | Create a new WhatsApp group |
| `agent.group.invite` | Invite participants to a group |
| `agent.group.list` | List available groups |
| `group.getContext` | Get group metadata and recent activity |
| `webhook_manager` | Manage webhooks via A2A |

---

### agent.message.send

Send a WhatsApp message through the A2A protocol.

**Request:**

```json
{
  "jsonrpc": "2.0",
  "method": "agent.message.send",
  "params": {
    "session_id": "a1b2c3d4-...",
    "to": "+5511999999999",
    "message": "Hello from Agent!",
    "metadata": {
      "source_agent": "my-crm-agent",
      "correlation_id": "req-123"
    }
  },
  "id": 1
}
```

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `session_id` | string | Yes | UUID of the WhatsApp session |
| `to` | string | Yes | E.164 phone number (e.g., `+5511999999999`) |
| `message` | string | Yes | Message text (max 4096 chars) |
| `metadata` | object | No | Arbitrary metadata for tracking |

**Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "message_id": "wa-msg-id-...",
    "status": "sent",
    "timestamp": "2026-02-11T10:05:00Z"
  },
  "id": 1
}
```

### agent.group.create / agent.group.invite / agent.group.list

Group management methods share a common pattern:

```json
// Create group
{"jsonrpc":"2.0","method":"agent.group.create","params":{"session_id":"...","name":"Support Team","participants":["+5511999999999"]},"id":2}

// Invite to group
{"jsonrpc":"2.0","method":"agent.group.invite","params":{"session_id":"...","group_id":"[email protected]","participants":["+5511777777777"]},"id":3}

// List groups (supports limit/offset pagination)
{"jsonrpc":"2.0","method":"agent.group.list","params":{"session_id":"...","limit":20,"offset":0},"id":4}
```

### group.getContext

Retrieve group metadata and recent activity for a monitored group.

```json
{"jsonrpc":"2.0","method":"group.getContext","params":{"session_id":"...","group_id":"[email protected]","limit":50},"id":5}
```

### webhook_manager

Manage webhooks via A2A. Actions: `create`, `list`, `update`, `delete`

```json
{"jsonrpc":"2.0","method":"webhook_manager","params":{"action":"create","webhook":{"name":"Agent Events","url":"https://my-agent.com/events","events":["message.received"]}},"id":6}
```

---

### JSON-RPC Error Codes

| Code | Meaning |
|------|---------|
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| -32000 | Rate limited |
| -32001 | Content policy violation |
| -32002 | Safeguard blocked |

**Error response:**

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid phone number format. Expected E.164 (e.g., +5511999999999)"
  },
  "id": 1
}
```

---

## Content Policy

Configure content filtering rules for A2A communications. Policies control what content agents can send and receive.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/a2a-policy/settings` | Get policy settings |
| PUT | `/a2a-policy/settings` |