Quick Start

This guide will help you get started with the WhatsApp SDK Python in just a few minutes.

Prerequisites

Before you begin, you’ll need:

  1. A WhatsApp Business Account

  2. A Meta App with WhatsApp Business API access

  3. Your credentials:

    • Phone Number ID: Your WhatsApp Business phone number ID

    • Access Token: Your Meta app access token

    • App Secret (optional): For webhook signature validation

    • Webhook Verify Token (optional): For webhook setup

Basic Setup

Initialize the Client

from whatsapp_sdk import WhatsAppClient

client = WhatsAppClient(
    phone_number_id="YOUR_PHONE_NUMBER_ID",
    access_token="YOUR_ACCESS_TOKEN"
)

Using Environment Variables

Create a .env file:

WHATSAPP_PHONE_NUMBER_ID=your_phone_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_APP_SECRET=your_app_secret
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_verify_token

Then initialize from environment:

from whatsapp_sdk import WhatsAppClient

client = WhatsAppClient.from_env()

Send Your First Message

Text Message

response = client.messages.send_text(
    to="+1234567890",
    body="Hello from WhatsApp SDK!"
)

print(f"Message sent! ID: {response.messages[0].id}")

Image Message

response = client.messages.send_image(
    to="+1234567890",
    image="https://example.com/image.jpg",
    caption="Check out this image!"
)

Template Message

response = client.templates.send(
    to="+1234567890",
    template_name="hello_world",
    language_code="en_US"
)

Handle Webhooks

Basic Webhook Setup

Here’s a simple FastAPI webhook handler:

from fastapi import FastAPI, Request, Header, Query

app = FastAPI()

@app.get("/webhook")
def verify_webhook(
    hub_mode: str = Query(None, alias="hub.mode"),
    hub_verify_token: str = Query(None, alias="hub.verify_token"),
    hub_challenge: str = Query(None, alias="hub.challenge")
):
    """Verify webhook during setup."""
    result = client.webhooks.handle_verification(
        hub_mode, hub_verify_token, hub_challenge
    )
    if result:
        return result
    return {"error": "Invalid token"}, 403

@app.post("/webhook")
async def handle_webhook(
    request: Request,
    x_hub_signature_256: str = Header(None)
):
    """Handle incoming webhook events."""
    body = await request.body()

    # Validate and parse the event
    event = client.webhooks.handle_event(x_hub_signature_256, body)

    # Extract messages
    messages = client.webhooks.extract_messages(event)
    for message in messages:
        if message.type == "text":
            print(f"Received text: {message.text.body}")

            # Echo the message back
            client.messages.send_text(
                to=message.from_,
                body=f"You said: {message.text.body}"
            )

    return {"status": "ok"}

Common Patterns

Using Pydantic Models

The SDK supports Pydantic models for type safety:

from whatsapp_sdk.models import TextMessage, Contact, Name, Phone

# Text message with Pydantic
text_msg = TextMessage(
    body="Hello with type safety!",
    preview_url=True
)
response = client.messages.send_text(to="+1234567890", text=text_msg)

# Contact with Pydantic
contact = Contact(
    name=Name(
        formatted_name="John Doe",
        first_name="John",
        last_name="Doe"
    ),
    phones=[Phone(phone="+1234567890", type="MOBILE")]
)
response = client.messages.send_contact(
    to="+9876543210",
    contacts=[contact]
)

Error Handling

from whatsapp_sdk.exceptions import WhatsAppError

try:
    response = client.messages.send_text(
        to="+invalid_number",
        body="This will fail"
    )
except WhatsAppError as e:
    print(f"Error: {e.message}")
    print(f"Error code: {e.code}")
    print(f"Error details: {e.details}")

Media Upload

# Upload a local file
upload_response = client.media.upload("/path/to/image.jpg")
media_id = upload_response.id

# Send using the media ID
response = client.messages.send_image(
    to="+1234567890",
    image=media_id,
    caption="Uploaded image"
)

# Download media
content = client.media.download(media_id)
with open("downloaded.jpg", "wb") as f:
    f.write(content)

Best Practices

  1. Always Use Environment Variables: Never hardcode credentials

  2. Handle Errors: Always wrap API calls in try-except blocks

  3. Validate Phone Numbers: Ensure phone numbers include country code

  4. Use Pydantic Models: Get type safety and validation

  5. Implement Retry Logic: The SDK has built-in retries, but handle failures gracefully

  6. Secure Webhooks: Always validate webhook signatures in production

Next Steps