evolution-whatsapp

A modern Python client for Evolution API v2 — send and receive WhatsApp messages from Python.

evolution-whatsapp is the Python twin of the R package evolution (source). It keeps the same mental model — a preconfigured client, snake_case send_* helpers, jid() — and adds a modern Python stack:

• httpx with sync and async clients (EvoClient / AsyncEvoClient)
• pydantic v2 models for webhook events + parse_webhook()
• structlog structured, timed logging via verbose=True
• local-file → base64 auto-encoding, automatic retries, typed errors
• optional FastAPI webhook router and pandas as_dataframe() for pipelines

This package is an independent wrapper for the Evolution API and is not affiliated with WhatsApp or Meta.

Installation

pip install evolution-whatsapp
# with extras:
pip install "evolution-whatsapp[fastapi]"   # webhook_router()
pip install "evolution-whatsapp[pandas]"    # as_dataframe()

The distribution is evolution-whatsapp; the import name is evolution_api (the bare evolution import is already taken on PyPI — see DECISIONS.md).

Quick start

from evolution_api import EvoClient, jid

client = EvoClient(
    base_url="https://YOUR-HOST",
    api_key="...",            # or set the EVO_APIKEY env var
    instance="yourInstance",
    timeout=30,               # or the EVOLUTION_TIMEOUT env var (default 60)
)

# Send a simple message (verbose logs timing + a response preview)
client.send_text("5581999990000", "Hello from Python!", verbose=True)

jid("+55 81 99999-0000")     # -> "5581999990000@s.whatsapp.net"

Async

import asyncio
from evolution_api import AsyncEvoClient

async def main():
    async with AsyncEvoClient(base_url="https://YOUR-HOST", api_key="...", instance="inst") as client:
        await client.send_text("5581999990000", "Hello from async Python!")

asyncio.run(main())

Functions overview

⚠️ send_buttons() / send_list(): interactive buttons and lists are not supported on the Baileys (WhatsApp Web) connector and may be discontinued — they work only on the Cloud API connector. Both emit a warning and suggest send_poll().

💡 Local files: send_media(), send_sticker() and send_whatsapp_audio() accept local paths (including ~/...), auto-encoded to base64.

Examples

# Media from a URL
client.send_media("5581999990000", "image", "image/png",
                  media="https://www.r-project.org/logo/Rlogo.png",
                  file_name="Rlogo.png", caption="R Logo")

# Media from a local file (auto base64)
client.send_media("5581999990000", "document", "application/pdf",
                  media="~/report.pdf", file_name="report.pdf")

# Poll
client.send_poll("5581999990000", "Favourite language?",
                 ["R", "Python", "Julia"], selectable_count=1)

# Contact (wuid auto-generated)
client.send_contact("5581999990000", {
    "fullName": "Jane Doe", "phoneNumber": "+5581999990000",
    "organization": "Company Ltd.", "email": "jane@example.com",
})

# Check numbers
client.check_is_whatsapp(["5581999990000", "5511988887777"])

Receiving webhooks

from evolution_api.webhooks import parse_webhook

event = parse_webhook(request_json)
if event.event_type == "MESSAGES_UPSERT":
    print(event.data.key.remote_jid, event.data.message)

FastAPI router (extra fastapi):

from fastapi import FastAPI
from evolution_api.webhooks import webhook_router

async def on_event(event):
    if event.event_type == "MESSAGES_UPSERT":
        ...

app = FastAPI()
app.include_router(webhook_router(on_event))

Drain to a DataFrame (extra pandas):

from evolution_api.webhooks import as_dataframe
df = as_dataframe([parse_webhook(p) for p in payloads])

Configuration

Relationship to the R package

This is a faithful port of StrategicProjects/evolution (CRAN). See the Parity with the R package page in the docs and DECISIONS.md for where Python idioms intentionally differ.

License

MIT © 2026 André Leite, Hugo Vasconcelos & Diogo Bezerra. See LICENSE.