Getting Started

To begin using the ka4ivan/laravel-notification-channel-instagram package, follow these minimal steps:

Install the Package

composer require ka4ivan/laravel-notification-channel-instagram

Set Up Instagram Bot

Obtain an access token and profile ID from the Instagram Graph API Explorer.

Add the credentials to config/services.php:

'instagram' => [
    'api_version' => env('INSTAGRAM_API_VERSION', '22.0'),
    'access_token' => env('INSTAGRAM_ACCESS_TOKEN', ''),
    'profile_id' => env('INSTAGRAM_PROFILE_ID', ''),
    'start_buttons' => [
        ['question' => 'Start', 'payload' => 'start'],
    ],
],

Configure Start Buttons Run the artisan command to set up interactive start buttons:
```
php artisan instagram:set-start-buttons
```

First Notification Use Case Create a notification class (e.g., ChannelConnected) and send a test message:

use NotificationChannels\Instagram\InstagramChannel;
use NotificationChannels\Instagram\InstagramMessage;
use Illuminate\Notifications\Notification;

class ChannelConnected extends Notification
{
    public function via($notifiable)
    {
        return [InstagramChannel::class];
    }

    public function toInstagram($notifiable)
    {
        return InstagramMessage::create()
            ->text('Welcome! Your channel is now connected.');
    }
}

Send the notification via:

$user->notify(new ChannelConnected());

Implementation Patterns

Common Workflows

Basic Text Notification

return InstagramMessage::create('Your order #12345 is confirmed!');

Rich Message with Attachments

return InstagramMessage::create()
    ->text('Check out your new product!')
    ->attach(AttachmentType::IMAGE, 'https://example.com/image.jpg');

Interactive Buttons

return InstagramMessage::create()
    ->text('How can we help?')
    ->buttons([
        Button::create('View Website', 'https://example.com')->isTypeWebUrl(),
        Button::create('Contact Support', ['user' => $userId])->isTypePostback(),
    ]);

Dynamic Routing Override routeNotificationForInstagram() in your User model:

public function routeNotificationForInstagram()
{
    return $this->instagram_id; // Store this in your DB
}

Integration Tips

Queue Notifications Use Laravel’s queue system to avoid API rate limits:
```
$user->notify(new ChannelConnected())->onQueue('instagram');
```

Override Default Config Set API version/tokens per message:

return InstagramMessage::create()
    ->setApiVersion('v23.0')
    ->setAccessToken('custom_token')
    ->text('Custom config message.');

Batch Sending Use attachMany() for carousel-style messages:

return InstagramMessage::create()
    ->attachMany(AttachmentType::IMAGE, [
        'https://example.com/image1.jpg',
        'https://example.com/image2.jpg',
    ]);

Error Handling Wrap notifications in a try-catch to log failures:

try {
    $user->notify(new ChannelConnected());
} catch (\Exception $e) {
    \Log::error('Instagram notification failed: ' . $e->getMessage());
}

Gotchas and Tips

Pitfalls

Access Token Expiry
- Instagram tokens expire. Use the Graph API Token Debugger to check validity.
- Fix: Implement a token refresh mechanism or rotate tokens periodically.
Rate Limiting
- Instagram’s API has strict rate limits (e.g., 200 calls/hour for sandbox).
- Fix: Use Laravel queues and implement exponential backoff for retries.
Profile ID Mismatch
- Ensure profile_id in config/services.php matches the Instagram Business account linked to your Facebook Page.
- Fix: Verify via the Graph API Explorer.
Attachment Size Limits
- Images: Max 8MB; Videos/Audio: Max 25MB.
- Fix: Compress media or split into multiple messages.
Button Limitations
- Only 3 buttons per message, and they must be either web_url or postback.
- Fix: Design UI to accommodate these constraints.

Debugging Tips

Enable API Logging Add this to config/services.php to log API responses:
```
'debug' => env('INSTAGRAM_DEBUG', false),
```
Test in Sandbox Use Instagram’s Sandbox Mode for development to avoid rate limits.

Check Webhook Status If using postback buttons, verify webhook subscriptions via:

curl -X GET "https://graph.instagram.com/me/webhooks?access_token=ACCESS_TOKEN"

Extension Points

Custom Button Types Extend the Button class to support additional types (e.g., phone_number):

namespace App\Notifications\Instagram;

use NotificationChannels\Instagram\Components\Button;

class CustomButton extends Button
{
    public function isTypePhoneNumber()
    {
        $this->type = 'phone_number';
        return $this;
    }
}

Override Message Builder Create a custom InstagramMessage class to add features:

namespace App\Notifications\Instagram;

use NotificationChannels\Instagram\InstagramMessage as BaseMessage;

class CustomMessage extends BaseMessage
{
    public function quickReplies($replies)
    {
        $this->quickReplies = $replies;
        return $this;
    }
}

Add Analytics Track sent messages by extending the channel:

namespace App\Notifications\Channels;

use NotificationChannels\Instagram\InstagramChannel as BaseChannel;

class CustomInstagramChannel extends BaseChannel
{
    public function send($notifiable, array $message)
    {
        \Log::info('Sent Instagram notification to: ' . $notifiable->instagram_id);
        parent::send($notifiable, $message);
    }
}

Configuration Quirks

API Version Always specify the latest stable version in config/services.php (e.g., v22.0). Check Instagram’s API Changelog for breaking changes.
Start Buttons The instagram:set-start-buttons command must be run after configuring access_token and profile_id. Re-run if buttons disappear.

Environment Variables Use .env for sensitive data:

INSTAGRAM_ACCESS_TOKEN=your_token_here
INSTAGRAM_PROFILE_ID=your_profile_id
INSTAGRAM_API_VERSION=v22.0

Laravel Notification Channel Instagram Laravel Package