# GatewayAPI SMS Integration Guide
This guide explains how to use the GatewayAPI SMS service that has been integrated into your Laravel application.
## Overview
The GatewayAPI integration provides a complete SMS notification channel that can be used to send SMS notifications to users. It includes:
- Custom notification channel (`GatewayApiSmsChannel`)
- Message class (`GatewayApiMessage`)
- Service provider for Laravel notification system
- Configuration in notification settings
- Database migration for phone numbers
## Configuration
### 1. Environment Variables
Add these to your `.env` file:
```env
GATEWAYAPI_TOKEN=your_api_token_here
GATEWAYAPI_SENDER=ZapaziMe
```
### 2. Notification Settings
Configure SMS settings in the admin panel under **Settings → Notification Settings**:
1. Enable SMS notifications
2. Set GatewayAPI token
3. Configure sender name (max 11 characters)
### 3. User Phone Numbers
Users must have a phone number set to receive SMS notifications. The phone number field has been added to the users table.
## Usage
### Basic Notification
Create a notification that uses the GatewayAPI channel:
```php
<?php
namespace App\Notifications;
use Illuminate\Notifications\Notification;
use App\Notifications\Messages\GatewayApiMessage;
class ExampleNotification extends Notification
{
public function via($notifiable)
{
return ['gatewayapi']; // Add other channels as needed
}
public function toGatewayApi($notifiable)
{
return GatewayApiMessage::create('Your SMS message here')
->sender('CustomSender'); // Optional: override default sender
}
}
```
### Multiple Channels
Send notifications via multiple channels:
```php
public function via($notifiable)
{
$channels = ['mail', 'database'];
if ($notifiable->phone) {
$channels[] = 'gatewayapi';
}
return $channels;
}
```
### Conditional SMS Sending
Control SMS sending based on user preferences:
```php
public function via($notifiable)
{
$channels = ['mail'];
// Only send SMS if user has SMS notifications enabled
if ($notifiable->getNotificationPreferences()->sms_bookings ?? false) {
$channels[] = 'gatewayapi';
}
return $channels;
}
```
## Message Options
The `GatewayApiMessage` class supports these options:
```php
GatewayApiMessage::create('Your message')
->sender('CustomSender') // Override default sender
->encoding('utf8') // Message encoding
->priority(1); // Message priority
```
## Phone Number Format
The GatewayAPI channel automatically formats phone numbers:
- Bulgarian numbers: `0888123456` → `359888123456`
- International format: `+359888123456` → `359888123456`
- Already formatted: `359888123456` → `359888123456`
## Error Handling
The channel includes comprehensive error handling:
- Failed API requests are logged
- Invalid phone numbers are skipped
- Empty messages are not sent
- API errors are captured and logged
## Testing
Run the included tests:
```bash
php artisan test tests/Feature/Notifications/GatewayApiSmsTest.php
```
## Integration with Existing Notifications
The following notifications have been updated to use GatewayAPI:
- `BookingStatusChanged` - Now uses `gatewayapi` channel instead of `twilio`
## Service Registration
The GatewayAPI channel is automatically registered via the `GatewayApiServiceProvider` which is included in the application's service providers.
## Monitoring
Check your application logs for SMS delivery status:
```bash
tail -f storage/logs/laravel.log | grep "GatewayAPI"
```
## API Response Handling
The channel processes GatewayAPI responses and returns detailed status information:
```php
[
'status' => 'sent', // or 'error'
'message_id' => 'abc123', // GatewayAPI message ID
'cost' => 0.05, // SMS cost in credits
'response' => [...] // Full API response
]
```
## Troubleshooting
### SMS Not Sending
1. Check if SMS notifications are enabled in settings
2. Verify GatewayAPI token is correct
3. Ensure user has a valid phone number
4. Check application logs for errors
### Invalid Phone Numbers
The channel automatically formats phone numbers but will skip invalid ones. Check logs for formatting issues.
### API Errors
All API errors are logged with detailed information including HTTP status codes and error messages from GatewayAPI.
## Security Notes
- GatewayAPI tokens are stored encrypted in the database
- Tokens are masked in the admin interface
- All API calls are made over HTTPS
- Phone numbers are validated before sending