Python - SDK

The Betatel SDK is designed to provide a straightforward and efficient way to implement SMS messaging within your Python applications. It abstracts the complexities of interacting directly with the underlying API, allowing developers to quickly and easily integrate SMS sending, status checking, and message tracking. This SDK is particularly useful for scenarios requiring reliable SMS communication and delivery tracking.

Installation

Install the SDK

pip install betatelsdk

Import the SDK

from betatelsdk import BetatelSDK

Initialization

Create an instance of the BetatelSDK:

sdk = BetatelSDK(
    api_key="YOUR_API_KEY",    # Replace with your API key
    user_id="YOUR_USER_ID"     # Replace with your user ID
)

# Access SMS service
sms_service = sdk.sms

Replace YOUR_API_KEY and YOUR_USER_ID with the actual values provided by your service.

warning

Security Notice:

Keep your API key secure. Do not expose it in client-side code or commit it to version control. Store it securely and retrieve it from a safe source.

Usage: Sending SMS Messages

Use the send method:

def send_sms(from_number, to, text):
    try:
        response = sdk.sms.send(
            from_number=from_number,     # sender number
            to=to,                       # recipient number
            text=text                    # message text
        )

        print("SMS sent successfully!")
        print(f"Message ID: {response['messageId']}")
        print(f"From: {response['from']}")
        print(f"To: {response['to']}")

        return response['messageId']
    except Exception as error:
        print(f"Failed to send SMS: {error}")
        raise

# Example usage:
message_id = send_sms("100200300", "+1987654321", "Hello from Betatel SDK!")
print(f"SMS sent with ID: {message_id}")

tip

Phone Number Formatting:

Ensure that the phone numbers you provide are in the correct format expected by your API. The 'from_number' should be your registered sender ID, and the 'to' number should include the country code.

Parameter	Type	Description
from_number	string	The sender number or sender ID.
to	string	The recipient's phone number.
text	string	The text message to be sent.

Usage: Checking SMS Status

Use the get_status method:

def check_sms_status(message_id):
    try:
        status = sdk.sms.get_status(message_id)
        
        print(f"SMS Status: {status['status']}")
        print(f"Message ID: {status['messageId']}")
        print(f"User ID: {status['userId']}")
        
        return status
    except Exception as error:
        print(f"Failed to get SMS status: {error}")
        raise

# Example usage:
status = check_sms_status("msg_123456")
if status['status'] == "Delivered":
    print("Message was delivered successfully!")

Parameter	Type	Description
message_id	string	The unique identifier of the SMS message.

Usage: Getting Complete SMS Details

Use the get_details method:

def get_sms_details(message_id):
    try:
        details = sdk.sms.get_details(message_id)
        
        print("=== SMS Details ===")
        print(f"Message ID: {details['messageId']}")
        print(f"Status: {details['status']}")
        print(f"From: {details['from']}")
        print(f"To: {details['to']}")
        print(f"Text: {details['text']}")
        print(f"Timestamp: {details['timestamp']}")
        print(f"Segments: {details['segments']}")
        print(f"User ID: {details['userId']}")
        
        return details
    except Exception as error:
        print(f"Failed to get SMS details: {error}")
        raise

Error Handling:

The SMS methods will raise exceptions if the API calls fail or return non-success status codes. Wrap your SMS calls within try...except blocks to handle these errors gracefully.

Example of complete integration

from betatelsdk import BetatelSDK

sdk = BetatelSDK(
    api_key="YOUR_API_KEY_HERE",   # Replace with your API key
    user_id="YOUR_USER_ID_HERE"    # Replace with your user ID
)

def complete_sms_workflow():
    try:
        # Step 1: Send SMS
        response = sdk.sms.send(
            from_number="100200300",           # sender number
            to="+1987654321",                  # recipient number
            text="Hello from Betatel SDK!"    # message text
        )
        
        print(f"SMS sent with ID: {response['messageId']}")
        
        # Step 2: Check status
        status = sdk.sms.get_status(response['messageId'])
        print(f"Current status: {status['status']}")
        
        # Step 3: Get full details
        details = sdk.sms.get_details(response['messageId'])
        print(f"Message segments: {details['segments']}")
        
    except Exception as error:
        print(f"SMS workflow failed: {error}")

complete_sms_workflow()

note

Important notes

• Ensure that phone numbers are in the correct format expected by your API.
• The sender number must be registered and approved for SMS sending.
• Keep your API key and user ID secure and do not expose them in client-side code.
• Monitor your SMS usage and delivery rates through the status and details methods.