grubgenie-waba-sdk

Python SDK for the GrubGenie WABA middleware. Send WhatsApp messages, manage templates, handle media, and receive inbound webhooks.

Install

pip install grubgenie-waba-sdk

With FastAPI webhook support:

pip install grubgenie-waba-sdk[fastapi]

Quick Start

import os
from waba_sdk import WabaClient

waba = WabaClient(
    base_url="https://waba.grubgenie.ai",
    service_key=os.environ["WABA_SERVICE_KEY"],
)

Messages

# Text message
await waba.messages.send_text("phone_number_id", "919999999999", "Hello!")

# Template message
await waba.messages.send_template(
    "phone_number_id", "919999999999",
    template_name="hello_world",
    language_code="en_US",
)

# Media message (image, video, document, audio)
await waba.messages.send_media(
    "phone_number_id", "919999999999",
    media_type="image",
    media_url="https://example.com/photo.jpg",
    caption="Check this out",
)

# Interactive message (buttons, lists)
await waba.messages.send_interactive("phone_number_id", "919999999999", {
    "type": "button",
    "body": {"text": "Pick one"},
    "action": {
        "buttons": [
            {"type": "reply", "reply": {"id": "yes", "title": "Yes"}},
            {"type": "reply", "reply": {"id": "no", "title": "No"}},
        ]
    },
})

# Mark message as read
await waba.messages.mark_as_read("phone_number_id", "wamid.xxx")

# Raw send (full control over body)
await waba.messages.send("phone_number_id", {
    "messaging_product": "whatsapp",
    "to": "919999999999",
    "type": "text",
    "text": {"body": "raw"},
})

Templates

WABA_ID = "your_waba_id"
PN_ID = "phone_number_id"

# List templates (single page)
page = await waba.templates.list(PN_ID, WABA_ID)

# List all templates (auto-paginates)
all_templates = await waba.templates.list_all(PN_ID, WABA_ID)

# Get template by name
template = await waba.templates.get(PN_ID, WABA_ID, "hello_world")

# Get template by ID
template = await waba.templates.get_by_id(PN_ID, WABA_ID, "123456789")

# Create template
await waba.templates.create(PN_ID, WABA_ID, {
    "name": "order_update",
    "language": "en_US",
    "category": "UTILITY",
    "components": [{"type": "BODY", "text": "Your order {{1}} is ready."}],
})

# Update template
await waba.templates.update(PN_ID, WABA_ID, "123456789", {
    "components": [{"type": "BODY", "text": "Order {{1}} updated."}],
})

# Delete template
await waba.templates.delete(PN_ID, WABA_ID, "order_update")

Media

# Upload
result = await waba.media.upload("phone_number_id", file_bytes, "photo.png", "image/png")
media_id = result["id"]

# Download
data = await waba.media.download(media_id, "phone_number_id")

Phone Numbers

# List phone numbers for a WABA
numbers = await waba.phone_numbers.list("phone_number_id", "waba_id")

# Register a phone number
await waba.phone_numbers.register("phone_number_id", pin="123456")

Cloud API Proxy

Direct access to any WhatsApp Cloud API endpoint through the middleware:

response = await waba.proxy("phone_number_id", "GET", "{waba_id}/phone_numbers")
print(response.json())

Inbound Webhooks (FastAPI)

from fastapi import FastAPI, Request
from waba_sdk import WabaWebhookHandler

app = FastAPI()

async def on_event(event):
    context = event["context"]  # { partnerId, phoneNumberId }
    raw = event["raw"]          # original Meta webhook body
    print(f"Message from partner {context['partnerId']}")

handler = WabaWebhookHandler(
    secret=os.environ["WABA_WEBHOOK_SECRET"],
    on_event=on_event,
)

@app.post("/webhooks/waba")
async def waba_webhook(request: Request):
    return await handler.handle(request)

Signature Verification

from waba_sdk import verify_signature

is_valid = verify_signature(payload_bytes, signature_header, secret)

Requirements

• Python >= 3.10
• httpx >= 0.27
• fastapi >= 0.115 (optional, for webhook handler)