Moltflow A2a

• "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 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 on Ethereum mainnet via ERC-8004. Agent card: https://molt.waiflow.app/.well-known/erc8004-agent.json

Required API Key Scopes

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.

Agent Card

GET https://apiv2.waiflow.app/.well-known/agent.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.

Get Public Key

GET /agent/public-key

{"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.

Request Format

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

Response Format

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

Available Methods

agent.message.send

Send a WhatsApp message through the A2A protocol.

Request:

{
  "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:

Response:

{
  "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:

// 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.

{"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

{"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

Error response:

{
  "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.

Get / Update Settings

GET /a2a-policy/settings returns current policy. PUT /a2a-policy/settings updates it.

{
  "enabled": true,
  "input_sanitization_enabled": true,
  "output_filtering_enabled": true,
  "block_urls": false,
  "block_phone_numbers": false,
  "max_message_length": 4096,
  "allowed_languages": ["en", "pt", "es"]
}

Create Custom Rule

POST /a2a-policy/rules

{
  "name": "Block competitor mentions",
  "pattern": "\\b(competitor1|competitor2)\\b",
  "action": "block",
  "description": "Prevent mentions of competitor brands"
}

Response 200 OK:

{
  "id": "rule-uuid-...",
  "name": "Block competitor mentions",
  "pattern": "\\b(competitor1|competitor2)\\b",
  "action": "block",
  "is_active": true,
  "created_at": "2026-02-11T10:00:00Z"
}

Test Content

POST /a2a-policy/test -- Test a message against your policy without sending it.

// Request
{"content": "Check out https://example.com for more info"}

// Response
{"allowed": false, "blocked_reason": "URL detected and block_urls is enabled", "matched_rules": ["built-in:block_urls"], "filtered_content": "Check out [URL REMOVED] for more info"}

Policy Stats

GET /a2a-policy/stats -- Returns total_checked, total_blocked, total_filtered, and top_rules with hit counts.

Rate Limits (A2A)

A2A methods have per-method rate limits:

Rate limit errors return JSON-RPC error code -32000.

Examples

Discover the MoltFlow agent

curl https://apiv2.waiflow.app/.well-known/agent.json

Send a message via A2A

# Use your scoped endpoint: /a2a/{tenant_id}/{session_id}/{webhook_id}
curl -X POST https://apiv2.waiflow.app/api/v2/a2a/{tenant_id}/{session_id}/{webhook_id} \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "agent.message.send",
    "params": {
      "session_id": "a1b2c3d4-...",
      "to": "+5511999999999",
      "message": "Hello from my AI agent!"
    },
    "id": 1
  }'

Set up a content policy rule

curl -X POST https://apiv2.waiflow.app/api/v2/a2a-policy/rules \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "No external links",
    "pattern": "https?://",
    "action": "block",
    "description": "Block all URLs in A2A messages"
  }'

Test content against policy

curl -X POST https://apiv2.waiflow.app/api/v2/a2a-policy/test \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Visit https://example.com for details"
  }'

Security Model

Security layers: TLS 1.3 (transport) -> X25519 ECDH (key exchange) -> AES-256-GCM (message encryption) -> API Key/JWT (auth) -> AgentSafeguard (input validation) -> A2AContentFilter (content policy) -> TieredRateLimiter (rate limits) -> AuditLog (full audit trail).

All encryption key management is handled server-side. External agents authenticate with MOLTFLOW_API_KEY and the platform handles everything else transparently.

Error Responses

Standard HTTP errors: 400 (bad request), 401 (unauthorized), 403 (policy violation), 404 (not found), 429 (rate limited). JSON-RPC errors use codes listed above.

Related Skills

• moltflow -- Core API: sessions, messaging, groups, labels, webhooks
• moltflow-outreach -- Bulk Send, Scheduled Messages, Custom Groups
• moltflow-leads -- Lead detection, pipeline tracking, bulk operations, CSV/JSON export
• moltflow-ai -- AI-powered auto-replies, voice transcription, RAG knowledge base, style profiles
• moltflow-reviews -- Review collection and testimonial management
• moltflow-admin -- Platform administration, user management, plan configuration