https://github.com/seven-io/php-client
The official PHP API Client for seven.io
https://github.com/seven-io/php-client
api-client cnam composer hlr mnp rcs sdk sms text2speech
Last synced: 4 months ago
JSON representation
The official PHP API Client for seven.io
- Host: GitHub
- URL: https://github.com/seven-io/php-client
- Owner: seven-io
- License: mit
- Created: 2019-11-12T14:21:28.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-12T12:43:40.000Z (5 months ago)
- Last Synced: 2026-01-12T19:46:56.390Z (5 months ago)
- Topics: api-client, cnam, composer, hlr, mnp, rcs, sdk, sms, text2speech
- Language: PHP
- Homepage: https://packagist.org/packages/seven.io/api
- Size: 7.42 MB
- Stars: 12
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# seven.io PHP SDK
[](https://packagist.org/packages/seven.io/api)
[](https://packagist.org/packages/seven.io/api)
[](LICENSE)
[](https://packagist.org/packages/seven.io/api)
**The official PHP SDK for the seven.io SMS Gateway API**
[Documentation](https://www.seven.io/en/docs/gateway/http-api/) • [API Reference](/docs) • [Support](https://www.seven.io/en/company/contact/) • [Dashboard](https://app.seven.io/)
---
## 📦 Installation
### Via Composer (recommended)
```bash
composer require seven.io/api
```
### Manual Installation
Download the latest release as [ZIP file](https://github.com/seven-io/php-client/releases/latest) and include it in your project.
## 🚀 Quick Start
### Send your first SMS
```php
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
```php
$params = (new SmsParams('Your message here', '+491234567890'))
->setFrom('YourBrand')
->setUnicode(true)
->setFlash(false);
$response = $smsResource->dispatch($params);
```
### Send bulk SMS
```php
$params = new SmsParams(
'Bulk message to multiple recipients',
['+491234567890', '+491234567891', '+491234567892']
);
$response = $smsResource->dispatch($params);
```
### Schedule SMS for later
```php
$params = (new SmsParams('Scheduled message', '+491234567890'))
->setDelay(new \DateTime('+1 hour'));
$response = $smsResource->dispatch($params);
```
### Perform HLR lookup
```php
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
```php
use Seven\Api\Resource\Balance\BalanceResource;
$balanceResource = new BalanceResource($client);
$balance = $balanceResource->get();
echo "Current balance: €" . $balance->getAmount();
```
### Text-to-Speech call
```php
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)
```php
$client = new Client(
apiKey: 'YOUR_API_KEY',
signingSecret: 'YOUR_SIGNING_SECRET'
);
```
### Error Handling
The SDK provides specific exceptions for different API error conditions:
```php
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:
```bash
# 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
```bash
# 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](CONTRIBUTING.md) 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](https://www.seven.io/en/docs/gateway/http-api/)
- 💬 [Contact Support](https://www.seven.io/en/company/contact/)
- 🐛 [Report Issues](https://github.com/seven-io/php-client/issues)
- 💡 [Feature Requests](https://github.com/seven-io/php-client/issues/new?labels=enhancement)
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
Made with ❤️ by [seven.io](https://www.seven.io)