📱 SMS Gateway for Android™ PHP API Client

August 19, 2026 · View on GitHub

A modern PHP client for seamless integration with the SMSGate API. Send SMS messages, manage devices, and configure webhooks through your PHP applications with this intuitive library.

🔖 Table of Contents

📱 SMS Gateway for Android™ PHP API Client

✨ Features

Builder Pattern: Fluent interface for message and settings configuration
PSR Standards: Compatible with any PSR-18 HTTP client
Comprehensive API: Access to all SMS Gateway endpoints
Error Handling: Structured exception management
Type Safety: Strict typing throughout the codebase
Encryption Support: End-to-end message encryption
Dual Authentication: Support for both Basic and JWT authentication
Token Management: Generate, use, and revoke JWT tokens with configurable scopes and TTL

⚙️ Prerequisites

PHP 7.4+
Composer
PSR-18 compatible HTTP client (e.g., Guzzle)
SMS Gateway for Android account

📦 Installation

composer require capcom6/android-sms-gateway

🚀 Quickstart

Sending an SMS

<?php

require 'vendor/autoload.php';

use AndroidSmsGateway\Client;
use AndroidSmsGateway\Domain\MessageBuilder;

// Initialize client with credentials
$client = new Client('your_login', 'your_password');

// Build message with fluent interface
$message = (new MessageBuilder('Your message text here.', ['+1234567890']))
    ->setTtl(3600)                  // Message time-to-live in seconds
    ->setSimNumber(1)               // Use SIM slot 1
    ->setWithDeliveryReport(true)   // Request delivery report
    ->setPriority(100)              // Higher priority message
    ->build();

// Send message
try {
    $messageState = $client->SendMessage($message);
    echo "✅ Message sent! ID: " . $messageState->ID() . PHP_EOL;
    
    // Check status after delay
    sleep(5);
    $updatedState = $client->GetMessageState($messageState->ID());
    echo "📊 Message status: " . $updatedState->State() . PHP_EOL;
} catch (\Exception $e) {
    echo "❌ Error: " . $e->getMessage() . PHP_EOL;
    exit(1);
}

Managing Devices

// List registered devices
$devices = $client->ListDevices();
echo "📱 Registered devices: " . count($devices) . PHP_EOL;

// Remove a device
try {
    $client->RemoveDevice('device-id-123');
    echo "🗑️ Device removed successfully" . PHP_EOL;
} catch (\Exception $e) {
    echo "❌ Device removal failed: " . $e->getMessage() . PHP_EOL;
}

🔐 Authentication

The SMSGate client supports two authentication methods: Basic Authentication and JWT (JSON Web Token) authentication. Each method has its own use cases and benefits.

Basic Authentication

// Initialize client with Basic authentication
$client = new Client('your_login', 'your_password');

JWT Authentication

JWT authentication uses bearer tokens for authentication.

Generating a JWT Token

use AndroidSmsGateway\Client;
use AndroidSmsGateway\Domain\TokenRequest;

// First, create a client with Basic authentication to generate a token
$basicClient = new Client('your_login', 'your_password');

// Create a token request with specific scopes and TTL
$tokenRequest = new TokenRequest(
    ['messages:send', 'messages:read'],  // Scopes for permissions
    3600                                 // Token TTL in seconds (optional)
);

// Generate the token
$tokenResponse = $basicClient->GenerateToken($tokenRequest);
$jwtToken = $tokenResponse->AccessToken();

echo "Token generated! Expires at: " . $tokenResponse->ExpiresAt() . PHP_EOL;

Using a JWT Token

// Initialize client with JWT authentication
$jwtClient = new Client(null, $jwtToken);

// Now use the client as usual
$message = (new MessageBuilder('Your message text here.', ['+1234567890']))->build();
$messageState = $jwtClient->SendMessage($message);

Revoking a JWT Token

// Revoke a token using its ID (jti)
$basicClient->RevokeToken($tokenResponse->ID());
echo "Token revoked successfully!" . PHP_EOL;

📚 Full API Reference

Client Initialization

The client supports two authentication methods: Basic Authentication and JWT Bearer Tokens.

Basic Authentication

$clientBasic = new Client(
    string $login,
    string $password,
    string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
    ?\Psr\Http\Client\ClientInterface $httpClient = null,
    ?\AndroidSmsGateway\Encryptor $encryptor = null
);

$clientJWT = new Client(
    null,                           // Set login to null for JWT
    string $jwtToken,               // JWT token as the second parameter
    string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
    ?\Psr\Http\Client\ClientInterface $httpClient = null,
    ?\AndroidSmsGateway\Encryptor $encryptor = null
);

Core Methods

Category	Method	Description
Messages	`SendMessage(Message $message)`	Send SMS message
	`GetMessageState(string $id)`	Get message status by ID
	`RefreshInbox(InboxRefreshRequest $request)`	Refresh inbox, deliver webhooks
Devices	`ListDevices()`	List registered devices
	`RemoveDevice(string $id)`	Remove device by ID
System	`HealthCheck()`	Check API health status
	`GetLogs(?string $from, ?string $to)`	Retrieve system logs
Settings	`GetSettings()`	Get account settings
	`PatchSettings(Settings $settings)`	Partially update account settings
	`ReplaceSettings(Settings $settings)`	Replace account settings
Webhooks	`ListWebhooks()`	List registered webhooks
	`RegisterWebhook(Webhook $webhook)`	Register new webhook
	`DeleteWebhook(string $id)`	Delete webhook by ID
Authentication	`GenerateToken(TokenRequest $request)`	Generate a new JWT token
	`RevokeToken(string $jti)`	Revoke a JWT token by ID

Builder Methods

// Message Builder
$message = (new MessageBuilder(string $text, array $recipients))
    ->setTtl(int $seconds)
    ->setSimNumber(int $simSlot)
    ->setWithDeliveryReport(bool $enable)
    ->setPriority(int $value)
    ->build();

🔒 Security Notes

Best Practices

Never store credentials in code - Use environment variables:

$login = getenv('SMS_GATEWAY_LOGIN');
$password = getenv('SMS_GATEWAY_PASSWORD');

Use HTTPS - Ensure all API traffic is encrypted
Validate inputs - Sanitize phone numbers and message content
Rotate credentials - Regularly update your API credentials

Encryption Support

use AndroidSmsGateway\Encryptor;

// Initialize client with encryption
$encryptor = new Encryptor('your-secret-passphrase');
$client = new Client($login, $password, Client::DEFAULT_URL, null, $encryptor);

👥 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Setup

git clone https://github.com/android-sms-gateway/client-php.git
cd client-php
composer install

📄 License

This library is open-sourced software licensed under the Apache-2.0 license.

Note: Android is a trademark of Google LLC. This project is not affiliated with or endorsed by Google.