{"id":31632684,"url":"https://github.com/alejandrovelez243/whatsapp-sdk","last_synced_at":"2026-05-18T06:12:14.501Z","repository":{"id":313669888,"uuid":"1052113489","full_name":"alejandrovelez243/whatsapp-sdk","owner":"alejandrovelez243","description":"A comprehensive **synchronous** Python SDK for WhatsApp Business Cloud API, following Meta's official documentation.","archived":false,"fork":false,"pushed_at":"2025-09-08T13:28:34.000Z","size":321,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T21:10:21.523Z","etag":null,"topics":["automation","chatbot","messaging","template","whatsapp","whatsapp-api","whatsapp-business-api","whatsapp-sdk","whatsappbot"],"latest_commit_sha":null,"homepage":"https://whatsapp-sdk.readthedocs.io/en/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alejandrovelez243.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T12:38:04.000Z","updated_at":"2025-09-08T13:35:50.000Z","dependencies_parsed_at":"2025-09-07T19:07:18.707Z","dependency_job_id":"6de2392e-b7ca-45c9-9c37-f925d6941eac","html_url":"https://github.com/alejandrovelez243/whatsapp-sdk","commit_stats":null,"previous_names":["alejandrovelez243/whatsapp-sdk"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alejandrovelez243/whatsapp-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrovelez243%2Fwhatsapp-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrovelez243%2Fwhatsapp-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrovelez243%2Fwhatsapp-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrovelez243%2Fwhatsapp-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alejandrovelez243","download_url":"https://codeload.github.com/alejandrovelez243/whatsapp-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandrovelez243%2Fwhatsapp-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33167431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T05:43:36.989Z","status":"ssl_error","status_checked_at":"2026-05-18T05:43:19.133Z","response_time":71,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","chatbot","messaging","template","whatsapp","whatsapp-api","whatsapp-business-api","whatsapp-sdk","whatsappbot"],"created_at":"2025-10-06T23:03:21.149Z","updated_at":"2026-05-18T06:12:14.451Z","avatar_url":"https://github.com/alejandrovelez243.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WhatsApp SDK Python\n\n[![PyPI version](https://badge.fury.io/py/whatsapp-sdk.svg)](https://badge.fury.io/py/whatsapp-sdk)\n[![Python Support](https://img.shields.io/pypi/pyversions/whatsapp-sdk.svg)](https://pypi.org/project/whatsapp-sdk/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://github.com/alejandrovelez243/whatsapp-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/alejandrovelez243/whatsapp-sdk/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/alejandrovelez243/whatsapp-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/alejandrovelez243/whatsapp-sdk)\n[![Documentation Status](https://readthedocs.org/projects/whatsapp-sdk/badge/?version=latest)](https://whatsapp-sdk.readthedocs.io/en/latest)\n\nA comprehensive **synchronous** Python SDK for WhatsApp Business Cloud API, following Meta's official documentation.\n\n## 🌟 Features\n\n- ✅ **100% Synchronous** - Simple, straightforward API without async complexity\n- 📘 **Fully Type-Hinted** - Complete type safety with Pydantic models\n- 🔄 **Auto-Retry Logic** - Built-in retry mechanism for robust API calls\n- 🔐 **Webhook Verification** - Secure webhook signature validation\n- 📦 **Media Management** - Upload, download, and manage media files\n- 💬 **Template Messages** - Full template message support\n- 🔔 **Interactive Messages** - Buttons, lists, and quick replies\n- 📍 **Location Messages** - Send and receive location data\n- 👥 **Contact Messages** - Share contact cards\n- ⌨️ **Typing Indicators** - Show typing status for better user experience\n- ✨ **Modern Python** - Supports Python 3.8+\n- 🛡️ **Secure**: Webhook signature validation and secure token handling\n- 📝 **Well-Documented**: Extensive documentation and examples\n\n## Installation\n\n```bash\npip install whatsapp-sdk\n```\n\n## Quick Start\n\n```python\nfrom whatsapp_sdk import WhatsAppClient\n\n# Initialize client\nclient = WhatsAppClient(\n    phone_number_id=\"YOUR_PHONE_NUMBER_ID\",\n    access_token=\"YOUR_ACCESS_TOKEN\"\n)\n\n# Send a text message\nresponse = client.messages.send_text(\n    to=\"+1234567890\",\n    body=\"Hello from WhatsApp SDK!\"\n)\nprint(f\"Message sent! ID: {response.messages[0].id}\")\n```\n\n## Configuration\n\n### Using Environment Variables\n\n```bash\nexport WHATSAPP_PHONE_NUMBER_ID=\"your_phone_id\"\nexport WHATSAPP_ACCESS_TOKEN=\"your_access_token\"\n```\n\n```python\nfrom whatsapp_sdk import WhatsAppClient\n\n# Create client from environment\nclient = WhatsAppClient.from_env()\n```\n\n### Direct Configuration\n\n```python\nclient = WhatsAppClient(\n    phone_number_id=\"YOUR_PHONE_NUMBER_ID\",\n    access_token=\"YOUR_ACCESS_TOKEN\",\n    app_secret=\"YOUR_APP_SECRET\",  # Optional: for webhook validation\n    webhook_verify_token=\"YOUR_VERIFY_TOKEN\",  # Optional: for webhook setup\n    api_version=\"v23.0\",  # Optional: API version\n    timeout=30,  # Optional: Request timeout\n    max_retries=3,  # Optional: Max retry attempts\n    rate_limit=80  # Optional: Requests per second\n)\n```\n\n## Usage Examples\n\n### Sending Messages\n\n#### Text Messages\n\n```python\n# Simple text\nresponse = client.messages.send_text(\n    to=\"+1234567890\",\n    body=\"Hello World!\"\n)\n\n# Text with URL preview\nresponse = client.messages.send_text(\n    to=\"+1234567890\",\n    body=\"Check out https://example.com\",\n    preview_url=True\n)\n\n# Using Pydantic model\nfrom whatsapp_sdk import TextMessage\n\nmessage = TextMessage(\n    body=\"Hello with Pydantic!\",\n    preview_url=True\n)\nresponse = client.messages.send_text(\n    to=\"+1234567890\",\n    text=message\n)\n```\n\n#### Media Messages\n\n```python\n# Send image\nresponse = client.messages.send_image(\n    to=\"+1234567890\",\n    image=\"https://example.com/image.jpg\",\n    caption=\"Look at this!\"\n)\n\n# Send document\nresponse = client.messages.send_document(\n    to=\"+1234567890\",\n    document=\"https://example.com/file.pdf\",\n    caption=\"Important document\",\n    filename=\"contract.pdf\"\n)\n\n# Send video\nresponse = client.messages.send_video(\n    to=\"+1234567890\",\n    video=\"https://example.com/video.mp4\",\n    caption=\"Check this out!\"\n)\n\n# Send audio\nresponse = client.messages.send_audio(\n    to=\"+1234567890\",\n    audio=\"https://example.com/audio.mp3\"\n)\n```\n\n#### Location Messages\n\n```python\nresponse = client.messages.send_location(\n    to=\"+1234567890\",\n    latitude=37.4847,\n    longitude=-122.1477,\n    name=\"Meta Headquarters\",\n    address=\"1 Hacker Way, Menlo Park, CA\"\n)\n```\n\n#### Contact Messages\n\n```python\nfrom whatsapp_sdk import Contact, Name, Phone, Email\n\ncontact = Contact(\n    name=Name(\n        formatted_name=\"John Doe\",\n        first_name=\"John\",\n        last_name=\"Doe\"\n    ),\n    phones=[\n        Phone(phone=\"+1234567890\", type=\"MOBILE\")\n    ],\n    emails=[\n        Email(email=\"john@example.com\", type=\"WORK\")\n    ]\n)\n\nresponse = client.messages.send_contact(\n    to=\"+9876543210\",\n    contacts=[contact]\n)\n```\n\n#### Interactive Messages\n\n```python\nfrom whatsapp_sdk import (\n    InteractiveMessage,\n    InteractiveBody,\n    InteractiveAction,\n    Button\n)\n\n# Button message\ninteractive = InteractiveMessage(\n    type=\"button\",\n    body=InteractiveBody(text=\"Choose an option:\"),\n    action=InteractiveAction(\n        buttons=[\n            Button(type=\"reply\", reply={\"id\": \"yes\", \"title\": \"Yes\"}),\n            Button(type=\"reply\", reply={\"id\": \"no\", \"title\": \"No\"})\n        ]\n    )\n)\n\nresponse = client.messages.send_interactive(\n    to=\"+1234567890\",\n    interactive=interactive\n)\n```\n\n### Message Status\n\n```python\n# Mark message as read\nresponse = client.messages.mark_as_read(\"wamid.xxx\")\n\n# Mark as read with typing indicator\nresponse = client.messages.mark_as_read(\"wamid.xxx\", typing_indicator=True)\n\n# Show typing indicator while processing\nresponse = client.messages.send_typing_indicator(\"wamid.xxx\")\n```\n\n### Template Messages\n\n```python\n# Send template message\nresponse = client.templates.send(\n    to=\"+1234567890\",\n    template_name=\"hello_world\",\n    language_code=\"en_US\"\n)\n\n# Send template with parameters\nfrom whatsapp_sdk.models import TemplateComponent, TemplateParameter\n\ncomponents = [\n    TemplateComponent(\n        type=\"body\",\n        parameters=[\n            TemplateParameter(type=\"text\", text=\"John\"),\n            TemplateParameter(type=\"text\", text=\"ABC123\")\n        ]\n    )\n]\n\nresponse = client.templates.send(\n    to=\"+1234567890\",\n    template_name=\"order_confirmation\",\n    language_code=\"en_US\",\n    components=components\n)\n```\n\n### Media Operations\n\n```python\n# Upload media from file\nresponse = client.media.upload(\"/path/to/image.jpg\")\nmedia_id = response.id\nprint(f\"Uploaded: {media_id}\")\n\n# Upload from bytes\nwith open(\"document.pdf\", \"rb\") as f:\n    response = client.media.upload_from_bytes(\n        file_bytes=f.read(),\n        mime_type=\"application/pdf\",\n        filename=\"document.pdf\"\n    )\n\n# Get media URL and info\nurl_response = client.media.get_url(\"media_id_123\")\nprint(f\"URL: {url_response.url}\")\nprint(f\"Size: {url_response.file_size} bytes\")\n\n# Download media to memory\ncontent = client.media.download(\"media_id_123\")\nwith open(\"downloaded.jpg\", \"wb\") as f:\n    f.write(content)\n\n# Download directly to file (memory efficient)\nsaved_path = client.media.download_to_file(\n    \"media_id_123\",\n    \"/path/to/save/file.jpg\"\n)\n\n# Delete media\nsuccess = client.media.delete(\"media_id_123\")\n```\n\n### Webhook Handling\n\n```python\n# FastAPI webhook example\nfrom fastapi import FastAPI, Request, Header, Query\n\napp = FastAPI()\n\n@app.get(\"/webhook\")\ndef verify_webhook(\n    hub_mode: str = Query(None, alias=\"hub.mode\"),\n    hub_verify_token: str = Query(None, alias=\"hub.verify_token\"),\n    hub_challenge: str = Query(None, alias=\"hub.challenge\")\n):\n    result = client.webhooks.handle_verification(\n        hub_mode, hub_verify_token, hub_challenge\n    )\n    if result:\n        return result\n    return {\"error\": \"Invalid token\"}, 403\n\n@app.post(\"/webhook\")\nasync def handle_webhook(\n    request: Request,\n    x_hub_signature_256: str = Header(None)\n):\n    body = await request.body()\n    event = client.webhooks.handle_event(x_hub_signature_256, body)\n\n    # Process messages\n    messages = client.webhooks.extract_messages(event)\n    for message in messages:\n        if message.type == \"text\":\n            print(f\"Received: {message.text.body}\")\n\n    return {\"status\": \"ok\"}\n```\n\n## Development Status\n\n### ✅ Completed Phases\n\n- **Phase 1**: Foundation \u0026 Setup\n  - Project structure\n  - Configuration management\n  - HTTP client setup\n  - Exception hierarchy\n\n- **Phase 2**: Core Models (Pydantic)\n  - Base models (BaseResponse, Error, Contact)\n  - Message models (Text, Image, Video, Audio, Document, Location, etc.)\n  - Contact models (Name, Phone, Email, Address, Organization)\n  - Template models (Template, Component, Parameter)\n  - Media models (Upload, URL, Delete responses)\n  - Webhook models (Event, Entry, Message, Status)\n\n- **Phase 3**: Services Implementation ✅\n  - **Messages Service**: All message types with full functionality\n  - **Templates Service**: Send, create, list, delete, update templates\n  - **Media Service**: Upload, download, delete media files\n  - **Webhooks Service**: Verification, signature validation, event parsing\n\n- **Phase 4**: Client Integration ✅\n  - All services wired and functional\n  - Environment configuration support\n  - Clean service-oriented architecture\n\n### 📋 Upcoming Phases\n\n- **Phase 5**: Testing\n  - Unit tests for all services\n  - Integration tests\n  - Mock responses\n\n- **Phase 6**: Examples \u0026 Documentation\n  - Basic usage examples\n  - Advanced examples\n  - API documentation\n\n- **Phase 7**: Quality \u0026 Release\n  - Code quality checks\n  - CI/CD setup\n  - PyPI release\n\n## API Design Principles\n\n- **Synchronous First**: No async/await complexity\n- **Pydantic Models**: Type-safe data structures\n- **Flexible Input**: Accept Pydantic models, dicts, or simple parameters\n- **Always Returns Pydantic**: Consistent, type-safe responses\n- **Service-Oriented**: Clean separation of concerns\n\n## Requirements\n\n- Python 3.8+\n- httpx\n- pydantic \u003e= 2.0\n\n## Contributing\n\nThis SDK is under active development. Contributions are welcome!\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/whatsapp-sdk.git\ncd whatsapp-sdk\n\n# Install with development dependencies\nuv sync --extra dev\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check src/ tests/\n\n# Run type checking\nuv run mypy src/\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [Full documentation](https://whatsapp-sdk.readthedocs.io) (coming soon)\n- **Issues**: [GitHub Issues](https://github.com/yourusername/whatsapp-sdk/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/whatsapp-sdk/discussions)\n\n## Disclaimer\n\nThis SDK is not officially affiliated with Meta or WhatsApp. It's an independent implementation following the official WhatsApp Business API documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrovelez243%2Fwhatsapp-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falejandrovelez243%2Fwhatsapp-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandrovelez243%2Fwhatsapp-sdk/lists"}