moltflow-a2a

name	moltflow-a2a
description	Agent-to-Agent protocol for MoltFlow: agent discovery, encrypted messaging, group management, content policy. Use when: a2a, agent card, agent message, encrypted, content policy, agent discovery.
source	MoltFlow Team
version	2.15.1
risk	safe
requiredEnv	["MOLTFLOW_API_KEY"]
primaryEnv	MOLTFLOW_API_KEY
disable-model-invocation	true

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 Free tier available. Sign up

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

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

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

---

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

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

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

Response Format

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

{
  "jsonrpc": "2.0",
  "method": "agent.message.send",
  "params": {
    "session_id": "a1b2c3d4-...",
    "to": "[phone]",
    "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., [phone])
message	string	Yes	Message text (max 4096 chars)
metadata	object	No	Arbitrary metadata for tracking

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":["[phone]"]},"id":2}

// Invite to group
{"jsonrpc":"2.0","method":"agent.group.invite","params":{"session_id":"...","group_id":"[e-mail]","participants":["[phone]"]},

group.getContext

Retrieve group metadata and recent activity for a monitored group.

{"jsonrpc":"2.0","method":"group.getContext","params":{"session_id":"...","group_id":"[e-mail]","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

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:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid phone number format. Expected E.164 (e.g., [phone])"
  },
  "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	Update policy settings
POST	/a2a-policy/rules	Create a custom rule
PUT	/a2a-policy/rules/{rule_id}	Update a rule
DELETE	/a2a-policy/rules/{rule_id}	Delete a rule
POST	/a2a-policy/rules/{rule_id}/toggle	Enable/disable a rule
POST	/a2a-policy/test	Test content against policy
POST	/a2a-policy/reset	Reset policy to defaults
GET	/a2a-policy/stats	Get policy enforcement stats
GET	/a2a-policy/safeguards	Get safeguard configuration

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:

Method	Limit
agent.message.send	30/min
agent.group.create	5/min
agent.group.invite	10/min
agent.group.list	60/min
group.getContext	30/min
webhook_manager	20/min

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": "[phone]",
      "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