Send Single SMS

import requests
import json

# Configuration
# Get your API key from: https://roycetalk.com/
# Format: XXXX_XXXXXXXXXXXXXXXXXXXXXXXX_
API_URL = "https://roycetalk.com/api/v1/sms-api/send/"
BEARER_TOKEN = "XXXX_XXXXXXXXXXXXXXXXXXXXXXXX_"

def send_sms(phone_number: str, message: str, sender_id: str):
    """
    Send a single SMS via RoyceTalk API
    
    Args:
        phone_number: Recipient phone number (format: +254XXXXXXXXX)
        message: SMS message content
        sender_id: Your approved sender ID
        
    Returns:
        dict: API response with message status
    """
    
    # Request headers with Bearer token
    headers = {
        "Authorization": f"Bearer {BEARER_TOKEN}",
        "Content-Type": "application/json"
    }
    
    # Request payload
    payload = {
        "phone_number": phone_number,
        "sender_id": sender_id,
        "text_message": message
    }
    
    try:
        # Make POST request
        response = requests.post(API_URL, json=payload, headers=headers)
        
        # Check if request was successful
        if response.status_code == 200:
            result = response.json()
            print("✓ SMS sent successfully!")
            print(f"Message ID: {result['data']['message_id']}")
            print(f"Status: {result['data']['status']}")
            print(f"Cost: KES {result['data']['cost']}")
            print(f"Balance: {result['data']['balance_after']} units")
            return result
            
        elif response.status_code == 403:
            error = response.json()
            print(f"✗ Authentication Error: {error['error']['message']}")
            return None
            
        elif response.status_code == 400:
            error = response.json()
            print(f"✗ Validation Error: {error['message']}")
            if 'errors' in error and error['errors']:
                for err in error['errors']:
                    print(f"  - {err['message']}")
            return None
            
        else:
            print(f"✗ Unexpected Error: {response.status_code}")
            print(response.text)
            return None
            
    except requests.exceptions.RequestException as e:
        print(f"✗ Request failed: {str(e)}")
        return None

# Example usage
if __name__ == "__main__":
    result = send_sms(
        phone_number="+254712345678",
        message="Hello, this is a test message from Royce SMS API.",
        sender_id="RoyceLTD"
    )
    
    if result:
        print("\nFull Response:")
        print(json.dumps(result, indent=2))