sendgo/laravel

Laravel에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 공식 Laravel 패키지

sendgo/laravel은 sendgo/php 코어를 확장한 Laravel 전용 패키지입니다. ServiceProvider 자동 등록, Facade, Config 게시 등 Laravel 통합을 완벽하게 제공합니다.

목차

• 설치
• 빠른 시작
• Facade 사용법
• 상세 사용법
  • 알림톡
  • 친구톡
  • SMS / LMS / MMS
• 서비스 클래스 패턴
• Notification Channel
• Queue / Job 비동기 발송
• 예외 처리
• 설정 옵션
• 자주 묻는 질문

설치

composer require sendgo/laravel

Laravel의 패키지 자동 검색(Package Auto-Discovery)으로 ServiceProvider와 Facade가 자동 등록됩니다.

빠른 시작

1단계 — 환경변수 설정 (.env)

SENDGO_ACCESS_KEY=your_access_key
SENDGO_SECRET_KEY=your_secret_key
SENDGO_KAKAO_SENDER_KEY=your_kakao_key
SENDGO_SMS_SENDER_KEY=your_sms_key
SENDGO_API_VERSION=v2

2단계 (선택) — 설정 파일 게시

php artisan vendor:publish --tag=sendgo-config

3단계 — 알림톡 전송

<?php

use Sendgo\Php\Sendgo;

class OrderController extends Controller
{
    public function __construct(private Sendgo $sendgo) {}

    public function confirm(Order $order): JsonResponse
    {
        $this->sendgo->alimtalk->send([
            'templateCode' => 'ORDER_CONFIRM_001',
            'contacts'     => [
                [
                    'contact' => $order->user->phone,
                    'name'    => $order->user->name,
                    'var1'    => $order->number,
                    'var2'    => number_format($order->total) . '원',
                ],
            ],
        ]);

        return response()->json(['success' => true]);
    }
}

Facade 사용법

<?php

use Sendgo\Laravel\Facades\Sendgo;

// 알림톡 발송
Sendgo::alimtalk()->send([
    'templateCode' => 'ORDER_CONFIRM_001',
    'contacts'     => [['contact' => '01012345678', 'var1' => 'ORD-001']],
]);

// SMS 발송
Sendgo::sms()->sendSms([
    'content'  => '[인증] 인증번호: 123456',
    'contacts' => [['contact' => '01012345678']],
]);

상세 사용법

알림톡

<?php

use Sendgo\Php\Sendgo;

// 다건 발송
app(Sendgo::class)->alimtalk->send([
    'templateCode' => 'ORDER_CONFIRM_001',
    'contacts'     => [
        ['contact' => '01011111111', 'name' => '홍길동', 'var1' => 'ORD-001', 'var2' => '29,000원'],
        ['contact' => '01022222222', 'name' => '김철수', 'var1' => 'ORD-002', 'var2' => '15,000원'],
        ['contact' => '01033333333', 'name' => '이영희', 'var1' => 'ORD-003', 'var2' => '52,000원'],
    ],
]);

// 예약 발송
app(Sendgo::class)->alimtalk->send([
    'templateCode' => 'PROMO_SUMMER_2026',
    'scheduleType' => 'SCHEDULED',
    'at'           => '2026-07-28 09:00:00',
    'contacts'     => [['contact' => '01012345678', 'var1' => '여름 한정 50% 할인']],
]);

// SMS 자동 대체 발송
app(Sendgo::class)->alimtalk->send([
    'templateCode' => 'DELIVERY_START_001',
    'replaceSms'   => 'Y',
    'smsSubject'   => '[배송 시작 안내]',
    'smsContent'   => "주문하신 상품이 출고되었습니다.\n송장번호: #{var2}",
    'contacts'     => [['contact' => '01012345678', 'var1' => 'ORD-001', 'var2' => '1234567890']],
]);

친구톡

<?php

// 텍스트형
app(Sendgo::class)->friendtalk->send([
    'content'  => '안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.',
    'contacts' => [['contact' => '01012345678']],
]);

// 이미지형
app(Sendgo::class)->friendtalk->send([
    'messageType' => 'FI',
    'content'     => '이번 주 특가 상품을 확인하세요!',
    'imageUrl'    => 'https://cdn.example.com/banner.jpg',
    'imageLink'   => 'https://example.com/event',
    'contacts'    => [['contact' => '01012345678']],
]);

// 버튼 포함
app(Sendgo::class)->friendtalk->send([
    'content'  => '7월 쿠폰이 도착했습니다! 지금 바로 사용하세요.',
    'buttons'  => [
        ['name' => '쿠폰 받기', 'type' => 'WL', 'linkMo' => 'https://example.com/coupon'],
        ['name' => '고객센터', 'type' => 'WL', 'linkMo' => 'https://example.com/cs'],
    ],
    'contacts' => [['contact' => '01012345678']],
]);

SMS / LMS / MMS

<?php

// SMS (90자 이하)
app(Sendgo::class)->sms->sendSms([
    'content'  => '[Sendgo] 인증번호: 123456 (5분 이내 입력)',
    'contacts' => [['contact' => '01012345678']],
]);

// LMS (장문, 2,000자 이하)
app(Sendgo::class)->sms->sendLms([
    'subject'  => '[중요] 서비스 점검 안내',
    'content'  => "안녕하세요. 서비스 점검이 예정되어 있습니다.\n\n■ 일시: 2026-07-25 02:00 ~ 06:00\n■ 영향: 전체 서비스",
    'contacts' => [['contact' => '01012345678']],
]);

// MMS (이미지 포함)
app(Sendgo::class)->sms->sendMms([
    'subject'  => '[이벤트] 7월 특가',
    'content'  => '이번 달 특가 상품을 확인하세요!',
    'contacts' => [['contact' => '01011111111'], ['contact' => '01022222222']],
]);

서비스 클래스 패턴

<?php
// app/Services/NotificationService.php

namespace App\Services;

use Sendgo\Php\Sendgo;
use Sendgo\Php\Exception\SendgoException;
use Illuminate\Support\Facades\Log;

class NotificationService
{
    public function __construct(private Sendgo $sendgo) {}

    public function sendOrderConfirm(string $phone, string $orderNo, int $amount): void
    {
        $this->sendgo->alimtalk->send([
            'templateCode' => 'ORDER_CONFIRM_001',
            'contacts'     => [
                ['contact' => $phone, 'var1' => $orderNo, 'var2' => number_format($amount) . '원'],
            ],
        ]);
    }

    public function sendShippingAlert(string $phone, string $trackingNo): void
    {
        $this->sendgo->alimtalk->send([
            'templateCode' => 'SHIPPING_001',
            'replaceSms'   => 'Y',
            'smsContent'   => "배송이 시작되었습니다.\n송장번호: {$trackingNo}",
            'contacts'     => [['contact' => $phone, 'var1' => $trackingNo]],
        ]);
    }

    public function sendVerificationCode(string $phone, string $code): void
    {
        try {
            // 알림톡 우선, 실패 시 SMS 대체
            $this->sendgo->alimtalk->send([
                'templateCode' => 'VERIFY_CODE_001',
                'replaceSms'   => 'Y',
                'smsContent'   => "[인증] 인증번호: {$code} (5분 이내 입력)",
                'contacts'     => [['contact' => $phone, 'var1' => $code]],
            ]);
        } catch (SendgoException $e) {
            Log::error('Sendgo 인증번호 발송 실패', [
                'phone'      => $phone,
                'error_code' => $e->getErrorCode(),
                'status'     => $e->getStatusCode(),
            ]);
            throw $e;
        }
    }
}

<?php
// app/Providers/AppServiceProvider.php

use App\Services\NotificationService;
use Sendgo\Php\Sendgo;

// ServiceProvider에 이미 Singleton으로 등록되어 있어 자동 주입 가능
$this->app->bind(NotificationService::class, function ($app) {
    return new NotificationService($app->make(Sendgo::class));
});

Notification Channel

<?php
// app/Notifications/OrderConfirmedNotification.php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use Sendgo\Php\Sendgo;

class OrderConfirmedNotification extends Notification
{
    public function __construct(private string $orderNo, private int $amount) {}

    public function via(object $notifiable): array
    {
        return ['sendgo_alimtalk'];
    }

    public function toSendgoAlimtalk(object $notifiable): array
    {
        return [
            'templateCode' => 'ORDER_CONFIRM_001',
            'contacts'     => [
                [
                    'contact' => $notifiable->phone,
                    'var1'    => $this->orderNo,
                    'var2'    => number_format($this->amount) . '원',
                ],
            ],
        ];
    }
}

Queue / Job 비동기 발송

<?php
// app/Jobs/SendAlimtalkJob.php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Sendgo\Php\Sendgo;
use Sendgo\Php\Exception\SendgoException;
use Illuminate\Support\Facades\Log;

class SendAlimtalkJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;
    public int $backoff = 10;

    public function __construct(
        private string $templateCode,
        private array $contacts,
    ) {}

    public function handle(Sendgo $sendgo): void
    {
        $sendgo->alimtalk->send([
            'templateCode' => $this->templateCode,
            'contacts'     => $this->contacts,
        ]);
    }

    public function failed(SendgoException $e): void
    {
        Log::error('알림톡 발송 실패', [
            'templateCode' => $this->templateCode,
            'error_code'   => $e->getErrorCode(),
        ]);
    }
}

// 디스패치 예시
SendAlimtalkJob::dispatch('ORDER_CONFIRM_001', [
    ['contact' => '01012345678', 'var1' => 'ORD-001'],
])->onQueue('notifications');

예외 처리

<?php

use Sendgo\Php\Exception\SendgoException;

try {
    app(Sendgo::class)->alimtalk->send([...]);
} catch (SendgoException $e) {
    Log::error('Sendgo 발송 실패', [
        'status'     => $e->getStatusCode(),
        'error_code' => $e->getErrorCode(),
        'endpoint'   => $e->getEndpoint(),
    ]);

    match ($e->getErrorCode()) {
        'INVALID_ACCESS_KEY',
        'INVALID_SECRET_KEY'    => alertOps('Sendgo 인증키 오류'),
        'INVALID_TEMPLATE_CODE' => logger()->warning('존재하지 않는 템플릿'),
        'PAYMENT_REQUIRED'      => alertOps('Sendgo 크레딧 부족'),
        'IP_NOT_ALLOWED'        => alertOps('허용되지 않은 IP'),
        default                 => null,
    };
}

설정 옵션

config/sendgo.php (vendor:publish 후 커스터마이징 가능):

자주 묻는 질문 (FAQ)

Q. sendgo/php와의 차이는 무엇인가요? A. sendgo/php는 프레임워크 독립적인 순수 PHP 코어 패키지입니다. sendgo/laravel은 이를 확장해 ServiceProvider 자동 등록, Facade, .env 설정 바인딩 등 Laravel 통합을 추가합니다.

Q. Laravel 10, 11, 12 모두 지원하나요? A. 네, illuminate/support ^10.0|^11.0|^12.0을 지원합니다.

Q. Facade를 사용하지 않고 DI로만 쓸 수 있나요? A. 네, Sendgo\Php\Sendgo를 생성자에서 타입힌트로 주입받아 사용할 수 있습니다.

Q. 테스트 시 Sendgo를 Mock 처리하려면? A. Sendgo\Php\Sendgo를 Mockery나 PHPUnit Mock으로 교체하면 됩니다.

관련 패키지

라이선스

MIT License © 2026 Sendgo

키워드: 카카오 알림톡 Laravel, 카카오 친구톡 Laravel, SMS 발송 Laravel, 알림톡 Laravel 패키지, Laravel 카카오 API 연동, Laravel Notification Channel, Sendgo Laravel SDK