README.md

seven.io PHP SDK

The official PHP SDK for the seven.io SMS Gateway API

Documentation • API Reference • Support • Dashboard

---

📦 Installation

Via Composer (recommended)

composer require seven.io/api

Manual Installation

Download the latest release as ZIP file and include it in your project.

🚀 Quick Start

Send your first SMS

<?php
require 'vendor/autoload.php';

use Seven\Api\Client;
use Seven\Api\Resource\Sms\SmsParams;
use Seven\Api\Resource\Sms\SmsResource;

// Initialize the client with your API key
$client = new Client('YOUR_API_KEY');

// Create SMS resource
$smsResource = new SmsResource($client);

// Send SMS
$response = $smsResource->dispatch(
    new SmsParams('Hello from seven.io!', '+491234567890')
);

echo "SMS sent successfully! ID: " . $response->getMessages()[0]->getId();

📱 Features

SMS Messaging

• ✅ Send SMS to single or multiple recipients
• ✅ Bulk SMS support
• ✅ Flash SMS
• ✅ Unicode support
• ✅ Delivery reports
• ✅ Schedule messages

Voice Calls

• ✅ Text-to-Speech calls
• ✅ Voice message broadcasts

Number Lookup

• ✅ HLR (Home Location Register) lookup
• ✅ Number format validation
• ✅ Carrier information
• ✅ Number portability check

Other Features

• ✅ Balance inquiry
• ✅ Pricing information
• ✅ Webhook management
• ✅ Contact management
• ✅ Analytics & Journal

💻 Usage Examples

Send SMS with custom sender

$params = (new SmsParams('Your message here', '+491234567890'))
    ->setFrom('YourBrand')
    ->setUnicode(true)
    ->setFlash(false);
    
$response = $smsResource->dispatch($params);

Send bulk SMS

$params = new SmsParams(
    'Bulk message to multiple recipients',
    ['+491234567890', '+491234567891', '+491234567892']
);

$response = $smsResource->dispatch($params);

Schedule SMS for later

$params = (new SmsParams('Scheduled message', '+491234567890'))
    ->setDelay(new \DateTime('+1 hour'));
    
$response = $smsResource->dispatch($params);

Perform HLR lookup

use Seven\Api\Resource\Lookup\LookupResource;

$lookupResource = new LookupResource($client);
$results = $lookupResource->hlr('+491234567890');
$hlr = $results[0];

echo "Current Carrier: " . $hlr->getCurrentCarrier()->getName() . "\n";
echo "Country: " . $hlr->getCountryName() . "\n";
echo "Reachable: " . $hlr->getReachable() . "\n";
echo "Ported: " . $hlr->getPorted() . "\n";

Check account balance

use Seven\Api\Resource\Balance\BalanceResource;

$balanceResource = new BalanceResource($client);
$balance = $balanceResource->get();

echo "Current balance: €" . $balance->getAmount();

Text-to-Speech call

use Seven\Api\Resource\Voice\VoiceResource;
use Seven\Api\Resource\Voice\VoiceParams;

$voiceResource = new VoiceResource($client);
$params = new VoiceParams('+491234567890', 'Hello, this is a test call');

$response = $voiceResource->call($params);

🔧 Advanced Configuration

Initialize with signing secret (for webhook validation)

$client = new Client(
    apiKey: 'YOUR_API_KEY',
    signingSecret: 'YOUR_SIGNING_SECRET'
);

Error Handling

The SDK provides specific exceptions for different API error conditions:

use Seven\Api\Exception\ApiException;
use Seven\Api\Exception\InvalidApiKeyException;
use Seven\Api\Exception\MissingAccessRightsException;
use Seven\Api\Exception\ForbiddenIpException;

try {
    $response = $smsResource->dispatch($params);
} catch (InvalidApiKeyException $e) {
    echo "Invalid API key provided";
} catch (MissingAccessRightsException $e) {
    echo "Missing access rights for this operation";
} catch (ForbiddenIpException $e) {
    echo "Your IP address is not allowed";
} catch (ApiException $e) {
    // Handles all other API error codes (100-903)
    // Common codes: 500 = Insufficient credit, 201 = Invalid sender, 202 = Invalid recipient
    echo "API Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

API Error Codes

Code	Description
100	SMS accepted and being sent
101	Sending to at least one recipient failed
201	Invalid sender
202	Invalid recipient number
301-305	Parameter validation errors
500	Insufficient account credit
600	Sending error occurred
900-903	Authentication/authorization errors

🧪 Testing

Run the test suite with your API credentials:

# Using production API key
SEVEN_API_KEY=your_api_key php vendor/bin/phpunit tests

# Using sandbox API key
SEVEN_API_KEY_SANDBOX=your_sandbox_key php vendor/bin/phpunit tests

Run specific tests

# Test only SMS functionality
php vendor/bin/phpunit tests/SmsTest.php

# Test with verbose output
php vendor/bin/phpunit tests --verbose

📚 API Resources

The SDK provides access to all seven.io API endpoints:

Resource	Description
AnalyticsResource	Analytics and statistics
BalanceResource	Account balance
ContactsResource	Contact management
HooksResource	Webhook management
JournalResource	Message history
LookupResource	Number lookup & validation
PricingResource	Pricing information
RcsResource	RCS messaging
SmsResource	SMS messaging
StatusResource	Delivery reports
SubaccountsResource	Subaccount management
ValidateForVoiceResource	Voice number validation
VoiceResource	Voice calls

🔑 Environment Variables

Variable	Description
SEVEN_API_KEY	Your production API key
SEVEN_API_KEY_SANDBOX	Your sandbox API key for testing
SEVEN_SIGNING_SECRET	Webhook signing secret
SEVEN_TEST_RECIPIENT	Custom recipient phone number for tests (default: 491716992343)

📄 Requirements

• PHP 8.2 or higher
• Composer (for installation)
• ext-curl
• ext-json

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🆘 Support

• 📖 API Documentation
• 💬 Contact Support
• 🐛 Report Issues
• 💡 Feature Requests

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by seven.io