How to Use the WhatsApp Business MCP in Pydantic AI

Q: If I use WhatsApp Business and Pydantic AI, can the agent handle diverse media types?

Yes. The sendmediamessage tool is robust, accepting various file formats (images, videos, documents, audio) provided they are at a public URL, and the type must be correctly specified.

Guaranteed, type-safe WhatsApp Business actions using Pydantic AI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect WhatsApp Business MCP to Pydantic AI

Create your Vinkius account to connect WhatsApp Business to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup WhatsApp Business with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Ensure valid data for `send_text_message`

The agent sends free-form conversational text messages by calling `send_text_message`. Because of the type-safe validation, if you pass an invalid E.164 phone number or malformed text, the agent fails loudly with a specific error—no silent mistakes. This guarantee is key when using tools like `send_location_pin`, which demands correctly formatted lat/lng coordinates for every pin dropped.

Structure complex replies with `send_quick_reply_buttons`

When guiding a user, the agent uses `send_quick_reply_buttons`. The tool requires an explanation text and a comma-separated list of labels. Pydantic validates that this input follows the expected format; you can't accidentally send three buttons with only one label.

Manage required parameters for `send_template_message`

Sending a Meta-approved template requires precision. The `send_template_message` tool mandates the exact template name and language code, which Pydantic validates at runtime. This prevents your agent from trying to send templates that don't exist. For content delivery, `send_media_message` needs an absolute file URL and a media type. The framework ensures these required strings are present before execution.

Setup guide

Set up WhatsApp Business MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "whatsapp-business-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to WhatsApp Business tools.",
)

result = await agent.run("List recent WhatsApp Business transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by WhatsApp Business. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect WhatsApp Business now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about WhatsApp Business MCP in Pydantic AI

The main benefit is correctness. Every time your agent uses a tool, like `send_emoji_reaction`, the output is validated against defined models. This means you never get silent corruption or hallucinated fields when interacting via WhatsApp Business.

It guarantees that the input structure is correct. For example, if `send_location_pin` expects two floating-point numbers (lat/lng), and you give it a string, the agent immediately stops with a validation error.

The server handles structured communication metadata, including messaging IDs (`wamid...`), geographic coordinates (lat/lng), public file URLs, template names, phone numbers, emojis, and button labels.

Yes. The `send_media_message` tool is robust, accepting various file formats (images, videos, documents, audio) provided they are at a public URL, and the type must be correctly specified.

The primary limitation is adherence to structure. The agent forces you to provide all required fields—like both a template name and language code for `send_template_message`—ensuring the call is always complete.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript