GronoSync Notification Channel для Laravel

Українська · English

Надсилайте Laravel-нотифікації через GronoSync — мультиканальну платформу обміну повідомленнями з підтримкою Telegram, WhatsApp, Instagram, Facebook, Viber, SMS, email та вбудованого чат-віджету.

Сайт · Кабінет клієнта · API: https://api.gronosync.com

Документація

Цей README — про Laravel-пакет. Усе про сам сервіс GronoSync — на docs.gronosync.com:

• Extern API — контакти, повідомлення, заявки, канали, ліміти
• Помилки й коди — кожен статус і code і що з ними робити
• Вебхуки — події, payload з повними прикладами JSON, перевірка, повтори
• Віджети на сайт — чат, форма й чат менеджера для вашої CRM
• Ключі API · Зміни API

Зміст

• Встановлення
• Налаштування
• Надсилання сповіщень
• Виклик API напряму
• Помилки
• Отримання вебхуків
• Тестування

Встановлення

composer require fomvasss/laravel-notification-channel-gronosync

Налаштування

Додайте до .env:

GRONOSYNC_URL=https://api.gronosync.com
GRONOSYNC_TOKEN=your_organization_token

Додайте до config/services.php:

'gronosync' => [
    'url'   => env('GRONOSYNC_URL'),
    'token' => env('GRONOSYNC_TOKEN'),
],

token — ключ API організації: кабінет GronoSync → Налаштування → Розширення → API. Показується лише раз, при створенні. Див. Ключі API.

Надсилання сповіщень

use NotificationChannels\Gronosync\GronosyncChannel;
use NotificationChannels\Gronosync\GronosyncMessage;

class OrderConfirmed extends \Illuminate\Notifications\Notification
{
    public function __construct(protected Order $order) {}

    public function via(mixed $notifiable): array
    {
        return [GronosyncChannel::class];
    }

    public function toGronosync(mixed $notifiable): GronosyncMessage
    {
        return GronosyncMessage::make()
            ->text("Ваше замовлення #{$this->order->id} підтверджено!")
            ->button('Переглянути замовлення', "https://shop.com/orders/{$this->order->id}");
    }
}

Маршрутизація

Поверніть контакт із notifiable-моделі — UUID у GronoSync або ваш ID, якщо синхронізуєте контакти через upsertContact() з external_id:

public function routeNotificationForGronosync(): ?string
{
    return $this->gronosync_contact_id; // UUID контакту в GronoSync
}

public function routeNotificationForGronosyncExternalId(): ?string
{
    return (string) $this->id; // той самий external_id, що передається в upsertContact()
}

Якщо визначено обидва, спершу береться routeNotificationForGronosync(), а external ID — лише коли той повертає порожнє значення. Без моделі: Notification::route('GronosyncExternalId', 'crm-42')->notify(...).

Або вкажіть контакт у повідомленні — рівно одним із contactId(), contactExternalId(), to():

GronosyncMessage::make()->contactExternalId((string) $customer->id)->text('Привіт!');

// новий контакт за ідентифікатором у каналі (телефон, Telegram ID, email…)
GronosyncMessage::make()->to('+380991234567')->channelId($smsChannelId)->text('Ласкаво просимо!');

Що означає to для кожного типу каналу і коли потрібен channelId() — Повідомлення.

Методи GronosyncMessage

Виклик API напряму

GronosyncApi — тонкий клієнт Extern API, повертає розібрану відповідь.

use NotificationChannels\Gronosync\GronosyncApi;

$api = app(GronosyncApi::class);

$api->upsertContact(['external_id' => (string) $user->id, 'name' => $user->name, 'phone' => $user->phone]);

$contact = $api->getContactByExternalId((string) $user->id);
$channel = collect($contact['channels'])->firstWhere('can_send', true);

$api->submitForm([
    'channel_id' => config('services.gronosync.form_channel_id'),
    'fields' => ['name' => $lead->name, 'email' => $lead->email, 'message' => $lead->message],
], idempotencyKey: "lead-{$lead->id}");

Невідомі ключі в upsertContact() / submitForm() / sendIncoming() відкидаються перед відправкою.

Помилки

Збої повертаються як CouldNotSendNotification:

• Прямий виклик GronosyncApi — виняток кидається.
• Через канал сповіщень — виняток не кидається: диспатчиться подія Laravel NotificationFailed з винятком у $event->data['exception'].

use Illuminate\Notifications\Events\NotificationFailed;
use NotificationChannels\Gronosync\Exceptions\CouldNotSendNotification;

Event::listen(function (NotificationFailed $event) {
    $exception = $event->data['exception'] ?? null;

    if ($event->channel === 'Gronosync'
        && $exception instanceof CouldNotSendNotification
        && $exception->getErrorCode() === 'chat_blocked') {
        $event->notifiable->update(['gronosync_blocked' => true]);
    }
});

Орієнтуйтесь на статус і code, а не на текст. Усі коди й що з ними робити — Помилки й коди.

Отримання вебхуків

GronoSync може сповіщати ваш застосунок про нові контакти, вхідні й вихідні повідомлення та чати, яким потрібен менеджер. Налаштування, події, payload і приклад контролера для Laravel — Вебхуки і Laravel.

Тестування

composer test
composer test:coverage

Безпека

Якщо ви виявили проблему безпеки, надішліть листа на fomin.vasil@gmail.com замість використання трекеру задач.

Участь у розробці

Деталі: CONTRIBUTING.md.

Автори

• Fomin Vasil
• All Contributors

Ліцензія

MIT License. Детальніше: LICENSE.md.