Metadata-Version: 2.4
Name: broadcastbuddy
Version: 1.0.1
Summary: Official Python SDK for Broadcast Buddy - Automated WhatsApp Messaging, Interactive Polls, Media & Hotline API.
Author-email: Broadcast Buddy Team <support@broadcastbuddy.app>
License: MIT
Project-URL: Homepage, https://broadcastbuddy.app
Project-URL: Documentation, https://broadcastbuddy.app/docs
Project-URL: Repository, https://github.com/Broadcast-Buddy/broadcast-buddy
Project-URL: Bug Tracker, https://github.com/Broadcast-Buddy/broadcast-buddy/issues
Keywords: whatsapp,whatsapp-api,messaging,broadcastbuddy,chatbots,automation,sdk,polls,notifications
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file
Dynamic: requires-python

# Broadcast Buddy Python SDK 🚀

Official, zero-dependency Python client library for the **[Broadcast Buddy](https://broadcastbuddy.app)** WhatsApp Gateway API. Send formatted text, interactive multi-choice polls, high-resolution media, PDF invoices, GPS location pins, and check real-time phone number registration on WhatsApp.

[![PyPI version](https://img.shields.io/pypi/v/broadcastbuddy.svg)](https://pypi.org/project/broadcastbuddy/)
[![Python versions](https://img.shields.io/pypi/pyversions/broadcastbuddy.svg)](https://pypi.org/project/broadcastbuddy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](https://opensource.org/licenses/MIT)

---

## ✨ Features

- **Zero External Dependencies** — Built directly on Python's standard `urllib` engine. Installs instantaneously anywhere.
- **100% Type Annotated** — Full PEP 484 type hints with `@dataclass` models and `py.typed` support for flawless PyCharm, VS Code, and mypy autocompletion.
- **WhatsApp Polls & Media** — First-class support for interactive polls, image captions, PDF documents, voice notes, and contact cards.
- **Live Verification** — Check if customer phone numbers are registered on WhatsApp before dispatching broadcasts.
- **Pythonic & CamelCase Aliasing** — Use standard Python `send_message()` or JS-style `sendMessage()`.

---

## 📦 Installation

```bash
pip install broadcastbuddy
```

Or with Poetry / Pipenv:

```bash
poetry add broadcastbuddy
```

---

## 🚀 Quickstart

```python
from broadcastbuddy import BroadcastBuddy

# Initialize with your API Key (Session ID)
bb = BroadcastBuddy("bb_live_YOUR_API_KEY")

# 1. Verify if a recipient is active on WhatsApp
check = bb.is_on_whatsapp("233240001122")
print("On WhatsApp:", check.is_registered)

# 2. Send a WhatsApp Text Message
res = bb.send_message("233240001122", "🚀 Hello from Broadcast Buddy Python SDK!")
print("Message Sent:", res.success)

# 3. Send an Interactive Multi-Choice Poll
bb.send_poll(
    phone="233240001122",
    question="Which feature should we build next?",
    options=[
        "AI Auto-Pilot Agent",
        "Custom Webhook Flows",
        "Enterprise CRM Sync"
    ],
    is_multi_select=False
)

# 4. Send Image with Caption (URL or Base64)
bb.send_image(
    phone="233240001122",
    image_source="https://example.com/receipt.png",
    caption="Your Payment Receipt #1092"
)

# 5. Send PDF Document / Invoice
bb.send_document(
    phone="233240001122",
    doc_source="data:application/pdf;base64,...",
    filename="Invoice_2026.pdf",
    caption="Here is your monthly invoice"
)

# 6. Check Hotline Connection Status
status = bb.get_status()
print("Hotline Status:", status.status, "Connected:", status.success)
```

---

## 📚 API Reference

### `BroadcastBuddy(api_key: str, timeout: int = 30)`

| Method | Arguments | Returns | Description |
| :--- | :--- | :--- | :--- |
| `send_message` | `phone, message, options=None` | `ApiResponse` | Send formatted text messages. |
| `send_poll` | `phone, question, options, is_multi_select=False` | `ApiResponse` | Send interactive multi-choice polls. |
| `send_image` | `phone, image_source, caption="", filename="image.png"` | `ApiResponse` | Send JPG/PNG/WebP image (URL or Base64). |
| `send_document`| `phone, doc_source, filename="doc.pdf", caption=""` | `ApiResponse` | Send PDF, Excel, Word, or zip document. |
| `send_audio` | `phone, audio_source, filename="audio.mp3"` | `ApiResponse` | Send audio voice notes. |
| `send_location` | `phone, latitude, longitude, name="", address=""` | `ApiResponse` | Send a GPS Location / Map Pin. |
| `send_contact` | `phone, name, contact_phone, organization=""` | `ApiResponse` | Send a Contact Card (vCard). |
| `schedule_message`| `phone, message, scheduled_time` | `ApiResponse` | Schedule message for future ISO timestamp. |
| `is_on_whatsapp`| `phone` | `WhatsAppNumberCheckResponse` | Verify if a number exists on WhatsApp. |
| `get_number_id`| `phone` | `dict` | Fetch standard WhatsApp JID format. |
| `get_status` | - | `SessionStatusResponse` | Check WhatsApp hotline connection state. |

---

## 📄 License

MIT © [Broadcast Buddy](https://broadcastbuddy.app)
