wapio 0.2.0

Official Python SDK for Wapio — send WhatsApp messages and manage WhatsApp sessions.

wapio

Official Python SDK for Wapio. Send WhatsApp messages, manage WhatsApp sessions, contacts, groups, channels, and decrypt inbound media.

pip install wapio

Python 3.9+ is required.

Features

• Sync and async clients built on httpx.
• Text, image, video, document, group, and channel message helpers.
• Session lifecycle: create, list, update, delete, connect, disconnect, QR, status, and key rotation.
• Contact management: list, details, profile picture, block, and unblock.
• Group management: list, metadata, participants add/remove, and settings.
• Inbound encrypted media decrypt helper.
• Rate-limit metadata and request IDs on every response.
• Automatic idempotency keys for message sends.

Quickstart

from wapio import Wapio

wapio = Wapio(api_key="bps_sk_...")

result = wapio.send_text(to="[phone]", text="Hello from Wapio")
print(result.data["msgId"])

Use a context manager when you want the HTTP client closed automatically:

with Wapio(api_key="bps_sk_...") as wapio:
    wapio.send_text(to="[phone]", text="Hi")

Async client

import asyncio
from wapio import AsyncWapio

async def main():
    async with AsyncWapio(api_key="bps_sk_...") as wapio:
        result = await wapio.send_text(to="[phone]", text="Hi")
        print(result.data["msgId"])

asyncio.run(main())

Authentication

Token	Format	Use
Personal Access Token	bps_pat_...	Create, update, delete, connect, disconnect, and rotate WhatsApp sessions.
Session key	bps_sk_...	Send messages and read resources for one connected WhatsApp session.

wapio = Wapio(
    personal_access_token="bps_pat_...",
    api_key="bps_sk_...",
)

Messages

wapio.send_text(to="[phone]", text="Hi")
wapio.send_image(to="[phone]", image_url="https://example.com/image.jpg", caption="Image")
wapio.send_video(to="[phone]", video_url="https://example.com/video.mp4")
wapio.send_document(
    to="[phone]",
    document_url="https://example.com/file.pdf",
    file_name="file.pdf",
)

Pass your own idempotency key when you need retry deduplication across processes:

wapio.send_text(
    to="[phone]",
    text="Order #42 shipped",
    idempotency_key="order:42:shipped",
)

Channels

Use the WhatsApp Channel ID ending in @newsletter.

wapio.send_channel_message(
    "120363428122592568@newsletter",
    "This week's release is live",
)

Message lifecycle

info = wapio.get_message_info("bps_msg_...")
wapio.edit_message("bps_msg_...", "Corrected text")
wapio.delete_message("bps_msg_...")

Sessions

created = wapio.create_session(label="Support line")
session_id = created.data["session"]["session_id"]
raw_session_key = created.data["session_api_key"]["raw"]

sessions = wapio.list_sessions(status="connected", limit=50)
session = wapio.get_session(session_id)

wapio.update_session(session_id, label="Support EU")
wapio.get_session_qrcode(session_id)
wapio.get_session_status()
wapio.connect_session(session_id)
wapio.disconnect_session(session_id)

rotated = wapio.regenerate_api_key(session_id)
print(rotated.data["session_api_key"]["raw"])

wapio.delete_session(session_id)

Store session_api_key.raw when it is returned. It is shown once.

Contacts

wapio.get_contacts()
wapio.get_contact("[phone]")
wapio.get_contact_profile_picture("[phone]")
wapio.block_contact("[phone]")
wapio.unblock_contact("[phone]")

Groups

group = wapio.create_group(
    subject="Customer updates",
    participants=["[e-mail]"],
)
group_jid = group.data["group_jid"]

wapio.get_groups()
wapio.get_group_metadata(group_jid)
wapio.get_group_participants(group_jid)
wapio.add_group_participants(group_jid, ["[e-mail]"])
wapio.remove_group_participants(group_jid, ["[e-mail]"])
wapio.update_group_settings(group_jid, {"announce": True})

wapio.send_text(to=group_jid, text="Hello group")

Media

For outbound media, pass a public HTTPS URL to send_image, send_video, or send_document.

Use decrypt_media for inbound encrypted WhatsApp media payloads:

media = wapio.decrypt_media({
    "mediaKey": "...",
    "directPath": "...",
    "url": "https://mmg.whatsapp.net/...",
    "type": "image",
})

Utilities

wapio.get_user()
wapio.check_if_on_whatsapp("[phone]")

Errors

SDK methods raise WapioAPIError for API errors and WapioConfigError for missing credentials before a request is sent.

try:
    wapio.send_text(to="[phone]", text="Hi")
except Exception as exc:
    print(exc)