A Python SDK designed to simplify interaction with the messaging API and webhook functionalities. It ensures seamless message management, automatic signature validation, and provides a robust foundation for developing scalable messaging applications.
The Messaging SDK is a Python library that allows developers to interact with the messaging API effortlessly. It handles authentication, API endpoint management, and webhook processing while ensuring security through HMAC signature validation.
.env file.Clone the repository:
git clone https://github.com/shiningflash/messaging-sdk.git
cd messaging-sdk
Create a virtual environment and install dependencies:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
Configure environment variables:
.env.example to .env: cp .env.example .env.env and adjust the values.Browse the API:
./docs/openapi.yaml.docker compose up.Initialize the SDK:
from sdk.client import ApiClient
from sdk.features.messages import Messages
# Initialize the API client and Messages module
api_client = ApiClient()
messages = Messages(api_client)
# Send a message
response = messages.send_message({
"to": {"id": "contact123"}, # Use the contact ID format for the recipient
"content": "Hello, World!",
"from": "+987654321" # Sender's phone number
})
print(response)
List Messages:
# List sent messages with pagination
response = messages.list_messages(page=1, limit=10)
print(response)
Example Response:
{
"messages": [
{
"id": "msg123",
"to": {
"id": "contact123",
"name": "John Doe",
"phone": "+1234567890"
},
"from": "+987654321",
"content": "Hello, World!",
"status": "delivered",
"createdAt": "2024-12-01T00:00:00Z"
}
],
"page": 1,
"quantityPerPage": 10
}
Run the webhook server:
uvicorn src.server.app:app --reload --port 3010
Configure the API to send events to your webhook endpoint (e.g., http://localhost:3010/webhooks).
Run all tests:
pytest
Generate a coverage report:
pytest --cov=src --cov-report=term-missing
Run specific test modules:
pytest tests/unit/test_sdk/
A detailed overview of the project structure, including descriptions of key files and directories.
.
├── .github/ # GitHub workflows for CI/CD
│ └── workflows/
│ └── ci.yml # Continuous Integration pipeline configuration
├── docs/ # Additional documentation
│ ├── openapi.yaml # OpenAPI docs
│ ├── sdk_usage.md # Comprehensive SDK usage documentation
│ └── webhook_guide.md # Webhook-specific documentation
├── src/ # Source code directory
│ ├── core/ # Core modules for shared logic
│ │ ├── __init__.py # Core module initialization
│ │ ├── exceptions/ # Exception handling modules
│ │ │ ├── __init__.py # Consolidated exception imports
│ │ │ ├── api.py # API-specific exceptions
│ │ │ ├── decorators.py # Decorators for exception handling
│ │ │ └── resource.py # Resource-specific exceptions
│ │ ├── config.py # Global configuration file for SDK and server
│ │ ├── logger.py # Logging utilities
│ │ ├── requests.py # Request helpers for SDK
│ │ ├── retry.py # Retry logic for transient failures
│ │ ├── security.py # HMAC validation and signature generation
│ │ └── validators.py # Common validation logic
│ ├── schemas/ # Schema definitions for request/response
│ │ ├── __init__.py # Schemas initialization
│ │ ├── contacts.py # Contact-related schemas
│ │ ├── errors.py # Error schemas (aligned with OpenAPI specs)
│ │ ├── messages.py # Message-related schemas
│ │ └── webhook.py # Webhook payload schemas
│ ├── sdk/ # SDK-related functionalities
│ │ ├── __init__.py # SDK initialization
│ │ ├── client.py # API client for interacting with the server
│ │ └── features/ # API feature modules
│ │ ├── __init__.py # Features initialization
│ │ ├── contacts.py # Contacts-related SDK operations
│ │ └── messages.py # Messages-related SDK operations
│ ├── server/ # Webhook server implementation
│ │ ├── __init__.py # Server initialization
│ │ ├── app.py # Main FastAPI application
│ │ └── schemas.py # Schemas specific to the webhook server
├── tests/ # Testing files for unit, integration, and E2E
│ ├── __init__.py # Test package initialization
│ ├── conftest.py # Pytest fixtures and test setup
│ ├── e2e/ # End-to-End (E2E) tests
│ │ ├── __init__.py # E2E tests initialization
│ │ ├── test_contacts_e2e.py # E2E tests for contacts feature
│ │ └── test_messages_e2e.py # E2E tests for messages feature
│ ├── integration/ # Integration tests
│ │ ├── __init__.py # Integration tests initialization
│ │ ├── test_contacts_integration.py # Integration tests for contacts
│ │ ├── test_messages_integration.py # Integration tests for messages
│ │ └── test_webhook.py # Integration tests for webhook functionality
│ └── unit/ # Unit tests for SDK and server
│ ├── test_sdk/ # SDK-specific unit tests
│ │ ├── __init__.py # SDK unit tests initialization
│ │ ├── test_client.py # Unit tests for API client
│ │ ├── test_contacts.py # Unit tests for contacts module
│ │ └── test_messages.py # Unit tests for messages module
│ └── test_server/ # Server-specific unit tests
│ ├── __init__.py # Server unit tests initialization
│ ├── test_route.py # Unit tests for API routes
│ └── test_signature_validation.py # Unit tests for signature validation
├── venv/ # Python virtual environment (not versioned)
├── .env.example # Example environment variables
├── docker-compose.yml # Docker Compose configuration
├── pytest.ini # Pytest configuration
├── requirements.in # Base Python dependencies
├── requirements.txt # Locked Python dependencies
├── README.md # Project documentation and usage guide
├── setup.py # Setup file to enable 'pip install .'
Here is the comprehensive architectural diagram for better understanding.
+----------------------------------------------------------+
| User |
| (Uses the SDK to send messages, manage contacts, |
| and handle webhook responses programmatically) |
+----------------------------------------------------------+
|
| 1. SDK API Calls
|
+----------------------------------------------------------+
| Messaging SDK |
| |
| +---------------------------------------------+ |
| | Features: | |
| | - `messages.py`: Send/manage messages | |
| | - `contacts.py`: Manage contact lists | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Utilities: | |
| | - `logger.py`: Logs interactions | |
| | - `validators.py`: Validates signatures | |
| | - `exceptions.py`: Handles errors | |
| | - `retry.py`: Implements retry logic | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Client (`client.py`): Handles API requests | |
| | - Appends authentication headers | |
| | - Sends REST API calls (e.g., GET, POST) | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 2. REST API Calls
v
+----------------------------------------------------------+
| API Server |
| |
| +---------------------------------------------+ |
| | Message Queue Simulation: | |
| | - Marks messages as `queued` | |
| | - Simulates delivery or failure | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Webhook Trigger: | |
| | - Sends event notifications to | |
| | configured Webhook Server URL | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 3. Webhook Event Notifications
v
+----------------------------------------------------------+
| Webhook Server |
| |
| +---------------------------------------------+ |
| | Endpoints: `/webhooks` | |
| | - Receives POST requests | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Signature Validation: | |
| | - Validates HMAC signature from | |
| | Authorization header | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Payload Processing: | |
| | - Parses incoming JSON payload | |
| | - Logs event details | |
| | - Prints payload to console | |
| +---------------------------------------------+ |
| |
| +---------------------------------------------+ |
| | Error Handling: | |
| | - 401 Unauthorized: Invalid Signature | |
| | - 422 Unprocessable Entity: Bad Payload | |
| +---------------------------------------------+ |
+----------------------------------------------------------+
|
| 4. Event Logs/Responses
v
+----------------------------------------------------------+
| Logging |
| |
| - SDK Logs (via `logger.py`): |
| Logs all user interactions, API calls, |
| and errors. |
| |
| - Webhook Server Logs: |
| Logs validated events and signature failures. |
| |
+----------------------------------------------------------+
Here is the comprehensive example for lifecycle of Messaging SDK and Webhook for more understanding.
1. User Sends a Message
+----------------------------------------------------------+
| User |
| - Calls `messages.send_message()` from the SDK |
| |
| Example Code: |
| sdk.messages.send_message( |
| to="+123456789", |
| from_sender="+987654321", |
| content="Hello, World!" |
| ) |
+----------------------------------------------------------+
|
v
2. SDK Sends API Request
+----------------------------------------------------------+
| Messaging SDK |
| |
| - Validates payload (e.g., phone number format). |
| - Prepares headers (`Authorization: Bearer <API_KEY>`). |
| - Sends HTTP POST request to the API. |
| |
| Request: |
| POST /messages |
| Headers: |
| - Authorization: Bearer <API_KEY> |
| Body: |
| { |
| "to": "+123456789", |
| "content": "Hello, World!", |
| "from_sender": "+987654321" |
| } |
+----------------------------------------------------------+
|
v
3. API Server Processes the Message
+----------------------------------------------------------+
| API Server |
| |
| - Marks message as `queued`. |
| - Simulates a delay for processing. |
| - Updates the message status to `delivered` or `failed`.|
| |
| Example Response: |
| { |
| "id": "msg123", |
| "status": "queued", |
| "createdAt": "2024-12-01T10:00:00Z" |
| } |
+----------------------------------------------------------+
|
v
4. API Triggers Webhook Notification
+----------------------------------------------------------+
| Webhook Trigger |
| |
| - Sends a POST request to the configured |
| webhook URL (e.g., `http://localhost:3010/webhooks`). |
| |
| Request: |
| POST /webhooks |
| Headers: |
| - Authorization: Bearer <HMAC-SIGNATURE> |
| Body: |
| { |
| "id": "msg123", |
| "status": "delivered", |
| "deliveredAt": "2024-12-01T12:00:00Z" |
| } |
+----------------------------------------------------------+
|
v
5. Webhook Server Processes the Event
+----------------------------------------------------------+
| Webhook Server |
| |
| - Validates the HMAC signature. |
| - Parses the payload. |
| - Logs and processes the event. |
| |
| Example Log: |
| - "Webhook received: {'id': 'msg123', 'status': 'delivered', |
| 'deliveredAt': '2024-12-01T12:00:00Z'}" |
| |
| Example Processing Code: |
| try: |
| verify_signature(payload, signature, secret) |
| print(f"Message {payload['id']} delivered.") |
| except ValueError: |
| print("Signature validation failed.") |
+----------------------------------------------------------+
|
v
6. Event Logging and Completion
+----------------------------------------------------------+
| Logging |
| |
| - SDK logs the sent message status and errors (if any). |
| - Webhook server logs validated payloads and events. |
| |
| Final Console Output: |
| "Message msg123 delivered." |
+----------------------------------------------------------+
FAQs
A Python SDK for managing messages and contacts, with webhook integration.
We found that messaging-py-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.