smswapi 1.0.0
A Python wrapper for the SMSWapi WhatsApp API
Requires Python: >=3.7
Keywords: smswapi, whatsapp, api, sms, messaging

# SMSWapi Python SDK

A production-ready Python wrapper for the [SMSWapi](https://smswapi.com) WhatsApp & SMS API.

## Installation

```bash
pip install smswapi
```

Or install from source:

```bash
git clone https://github.com/yourusername/smswapi.git
cd smswapi
pip install .
```

## Quick Start

```python
import smswapi

# Set your API secret globally (from Tools -> API Keys in dashboard)
smswapi.API_SECRET = "your_api_secret_here"

# Create client
client = smswapi.SMSWapi()

# Check credits
credits = client.get_credits()
print(f"Balance: {credits['data']['credits']} {credits['data']['currency']}")

# Send WhatsApp message
response = client.send_whatsapp(
    recipient="+40712034567",
    message="Hello from SMSWapi!",
    account="your_whatsapp_account_unique_id"
)

# Send SMS
response = client.send_sms(
    phone="+40712034567",
    message="Hello via SMS!",
    mode="credits",
    gateway="your_gateway_id"
)
```

## Configuration

```python
import smswapi

# Required: Your API secret
smswapi.API_SECRET = "your_api_secret"

# Optional: Default country code (auto-prefixes phone numbers)
smswapi.DEFAULT_COUNTRY_CODE = "40"  # Romania

# Optional: Request timeout in seconds (default: 30)
smswapi.TIMEOUT = 60

# Optional: Custom base URL
smswapi.BASE_URL = "https://smswapi.com/api"
```

## Client Initialization

```python
# Use global config
client = smswapi.SMSWapi()

# Or provide config per-client
client = smswapi.SMSWapi(
    secret="your_api_secret",
    default_country_code="40",
    timeout=60
)
```

## API Methods

### Account

```python
# Get remaining credits
client.get_credits()

# Get subscription info
client.get_subscription()

# Get partner earnings
client.get_earnings()
```

### Contacts

```python
# Create contact
client.create_contact(phone="+40712034567", name="John Doe", groups="1,2")

# Create group
client.create_group(name="My Group")

# Get contacts/groups
client.get_contacts(limit=10, page=1)
client.get_groups(limit=10, page=1)
client.get_unsubscribed(limit=10, page=1)

# Delete
client.delete_contact(contact_id=123)
client.delete_group(group_id=456)
client.delete_unsubscribed(contact_id=789)
```

### OTP (One-Time Password)

```python
# Send OTP via SMS
response = client.send_otp(
    phone="+40712034567",
    message="Your OTP is {{otp}}",
    otp_type="sms",
    mode="credits",
    gateway="your_gateway_id",
    expire=300
)
otp_code = response['data']['otp']

# Send OTP via WhatsApp
client.send_otp(
    phone="+40712034567",
    message="Your OTP is {{otp}}",
    otp_type="whatsapp",
    account="your_wa_account_id"
)

# Verify OTP
client.verify_otp(otp="123456")
```

### SMS

```python
# Send single SMS
client.send_sms(
    phone="+40712034567",
    message="Hello!",
    mode="credits",       # or "devices"
    gateway="gateway_id", # for credits mode
    # device="device_id", # for devices mode
    # sim=1,              # SIM slot for devices mode
    priority=0            # 0/1=immediate, 2=queued
)

# Send bulk SMS
client.send_sms_bulk(
    message="Hello everyone!",
    campaign="My Campaign",
    mode="credits",
    gateway="gateway_id",
    numbers=["+40712034567", "+40712034568"],
    # groups=["1", "2"],  # or use contact groups
)

# Get messages
client.get_sms_sent(limit=10, page=1)
client.get_sms_received(limit=10, page=1)
client.get_sms_pending(limit=10, page=1)
client.get_sms_campaigns(limit=10, page=1)
client.get_sms_message(message_id=123, message_type="sent")

# Campaign control
client.start_sms_campaign(campaign_id=123)
client.stop_sms_campaign(campaign_id=123)

# Delete
client.delete_sms_sent(message_id=123)
client.delete_sms_received(message_id=456)
client.delete_sms_campaign(campaign_id=789)
```

### WhatsApp

```python
# Send single message
client.send_whatsapp(
    recipient="+40712034567",
    message="Hello!",
    account="wa_account_unique_id",
    msg_type="text",      # "text", "media", or "document"
    priority=2            # 1=immediate, 2=queued
)

# Send with media
client.send_whatsapp(
    recipient="+40712034567",
    message="Check this image!",
    account="wa_account_id",
    msg_type="media",
    media_url="https://example.com/image.jpg",
    media_type="image"
)

# Send with document
client.send_whatsapp(
    recipient="+40712034567",
    message="Here's the document",
    account="wa_account_id",
    msg_type="document",
    document_url="https://example.com/file.pdf",
    document_type="pdf",
    document_name="report.pdf"
)

# Send bulk WhatsApp
client.send_whatsapp_bulk(
    message="Hello everyone!",
    campaign="My WA Campaign",
    account="wa_account_id",
    recipients=["+40712034567", "+40712034568"],
    # groups=["1", "2"],
)

# Get chats
client.get_wa_accounts(limit=10, page=1)
client.get_wa_sent(limit=10, page=1)
client.get_wa_received(limit=10, page=1)
client.get_wa_pending(limit=10, page=1)
client.get_wa_campaigns(limit=10, page=1)
client.get_wa_message(message_id=123, message_type="sent")

# WhatsApp groups
client.get_wa_groups(unique="wa_account_unique_id")
client.get_wa_group_contacts(unique="wa_account_id", gid="group_id")

# Validate phone number
client.validate_whatsapp(phone="+40712034567", unique="wa_account_id")

# Campaign control
client.start_wa_campaign(campaign_id=123)
client.stop_wa_campaign(campaign_id=123)

# Delete
client.delete_wa_sent(chat_id=123)
client.delete_wa_received(chat_id=456)
client.delete_wa_campaign(campaign_id=789)
client.delete_wa_account(unique="wa_account_id")
```

### WhatsApp Account Linking

```python
# Get available servers
client.get_wa_servers()

# Link new account (returns QR code)
result = client.link_whatsapp()
print(f"Scan QR: {result['data']['qrimagelink']}")

# Relink existing account
client.relink_whatsapp(unique="wa_account_id")

# Get account info after linking
client.get_wa_info(token="token_from_link")
```

### Android Devices

```python
# Get linked devices
client.get_devices(limit=10, page=1)

# Send USSD request
client.send_ussd(code="*123#", sim=1, device="device_unique_id")

# Get USSD requests
client.get_ussd(limit=10, page=1)
client.delete_ussd(ussd_id=123)

# Delete notification
client.delete_notification(notification_id=123)
```

### Gateways & Utilities

```python
# Get gateway rates
client.get_rates()

# Get URL shorteners
client.get_shorteners()
```

## Error Handling

```python
from smswapi import (
    SMSWapiError,
    AuthenticationError,
    PermissionError,
    InsufficientCreditsError
)

try:
    client.send_whatsapp(...)
except AuthenticationError:
    print("Invalid API secret")
except PermissionError as e:
    print(f"Missing permission: {e}")
except InsufficientCreditsError:
    print("Not enough credits")
except SMSWapiError as e:
    print(f"API error: {e}")
```

## License

MIT License - see [LICENSE](LICENSE) file.

## Links

- [SMSWapi Website](https://smswapi.com)
- [API Documentation](https://smswapi.com/dashboard/docs)
- [Dashboard](https://smswapi.com/dashboard)