WhatsApp Python API Tutorial: Send Messages Programmatically in 2026

export WALYTIC_API_KEY="your_api_key_here"
export WALYTIC_INSTANCE_ID="your_instance_id_here"

import requests
import os

API_KEY = os.environ["WALYTIC_API_KEY"]
INSTANCE_ID = os.environ["WALYTIC_INSTANCE_ID"]
BASE_URL = "https://api.walytic.com/api"

def send_whatsapp_text(phone: str, message: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/messages/send",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "instanceId": INSTANCE_ID,
            "to": phone,
            "type": "text",
            "text": {"body": message},
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

# Example
result = send_whatsapp_text("14155552671", "Hello from Python! 👋")
print(result)

def send_whatsapp_image(phone: str, image_url: str, caption: str = "") -> dict:
    response = requests.post(
        f"{BASE_URL}/messages/send",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={
            "instanceId": INSTANCE_ID,
            "to": phone,
            "type": "image",
            "image": {"url": image_url, "caption": caption},
        },
        timeout=15,
    )
    response.raise_for_status()
    return response.json()

# Send an order shipped notification with image
send_whatsapp_image(
    "14155552671",
    "https://yourstore.com/shipped-banner.jpg",
    "Your order #1234 has shipped! 📦 Expected delivery: Friday.",
)

def send_whatsapp_document(phone: str, doc_url: str, filename: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/messages/send",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={
            "instanceId": INSTANCE_ID,
            "to": phone,
            "type": "document",
            "document": {"url": doc_url, "filename": filename},
        },
        timeout=15,
    )
    response.raise_for_status()
    return response.json()

# Send an invoice PDF
send_whatsapp_document(
    "14155552671",
    "https://yourapp.com/invoices/INV-2026-001.pdf",
    "Invoice-2026-001.pdf",
)

def send_whatsapp_broadcast(phones: list[str], message: str, delay_seconds: int = 10) -> dict:
    response = requests.post(
        f"{BASE_URL}/messages/broadcast",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={
            "instanceId": INSTANCE_ID,
            "contacts": phones,
            "type": "text",
            "text": {"body": message},
            "options": {"delay": delay_seconds},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

# Send a payment reminder to overdue accounts
overdue_phones = ["14155552671", "14155552672", "14155552673"]
send_whatsapp_broadcast(
    overdue_phones,
    "Hi! This is a reminder that your invoice is due today. Reply PAID to confirm payment.",
    delay_seconds=10,
)

def get_message_status(message_id: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/messages/{message_id}/status",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

status = get_message_status("MSG_ID_HERE")
print(status)
# {"status": "read", "deliveredAt": "2026-04-29T10:30:02Z", "readAt": "2026-04-29T10:31:15Z"}

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["WALYTIC_WEBHOOK_SECRET"]

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    # Verify Walytic webhook signature
    signature = request.headers.get("X-Walytic-Signature", "")
    payload = request.get_data()
    expected = hmac.new(WEBHOOK_SECRET.encode(), payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    data = request.json
    if data.get("event") == "message.received":
        phone = data["from"]
        body = data["body"].lower()

        if "help" in body:
            send_whatsapp_text(phone, "Hi! Reply 1 for support, 2 for sales, 3 for billing.")
        elif body == "1":
            send_whatsapp_text(phone, "Connecting you to our support team now...")

    return jsonify({"status": "ok"}), 200

if __name__ == "__main__":
    app.run(port=5000)

from requests.exceptions import Timeout, HTTPError, ConnectionError

def safe_send(phone: str, message: str) -> bool:
    try:
        result = send_whatsapp_text(phone, message)
        return result.get("status") == "sent"
    except Timeout:
        print(f"Timeout sending to {phone} — will retry later")
    except HTTPError as e:
        code = e.response.status_code
        if code == 429:
            print("Rate limited — add a delay between requests")
        elif code == 401:
            print("Invalid API key — check WALYTIC_API_KEY environment variable")
        elif code == 400:
            print(f"Bad request — check phone format: {e.response.json()}")
    except ConnectionError:
        print("Network error — check connectivity")
    return False