Skip to content

Commit 4ca7519

Browse files
PalbahngmiyinePalbahngmiyine
authored
Merge pull request #23 from Palbahngmiyine/master
Enhance README and add example scripts for Kakao BMS message types
2 parents 86b2dca + 91c3abf commit 4ca7519

20 files changed

Lines changed: 892 additions & 2 deletions

‎README.md‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,44 @@ composer require solapi/sdk
2222

2323
## Usage
2424

25-
See [examples repository](https://github.com/solapi/solapi-php-examples)
25+
Examples live in `examples/` and are self-contained CLI scripts that load the root autoloader.
2626

27-
[//]: # (TODO: Need to add next solapi document link)
27+
Run an example:
28+
29+
```bash
30+
php examples/send_sms.php
31+
```
32+
33+
Each example contains placeholders like `ENTER_YOUR_API_KEY` and `ENTER_YOUR_API_SECRET`.
34+
Replace those values before running.
35+
Image assets used by some examples are in `examples/images/`.
36+
37+
**Examples**
38+
Inquiry:
39+
- `examples/get_balance.php` — get account balance
40+
- `examples/get_messages.php` — query message list with filters
41+
- `examples/get_statistics.php` — get message statistics
42+
43+
SMS / LMS / MMS:
44+
- `examples/send_sms.php` — send SMS (auto-upgrades to LMS by length)
45+
- `examples/send_lms.php` — send LMS
46+
- `examples/send_mms.php` — send MMS with image
47+
- `examples/send_overseas_sms.php` — send overseas SMS
48+
49+
Voice:
50+
- `examples/send_voice_message.php` — send voice message
51+
52+
Kakao Alimtalk:
53+
- `examples/send_alimtalk.php` — send Alimtalk
54+
55+
Kakao Brand Message (BMS):
56+
- `examples/send_brand_message.php` — send Brand Message
57+
- `examples/send_bms_free_text.php` — BMS FREE TEXT
58+
- `examples/send_bms_free_image.php` — BMS FREE IMAGE
59+
- `examples/send_bms_free_commerce.php` — BMS FREE COMMERCE
60+
- `examples/send_bms_free_carousel_feed.php` — BMS FREE CAROUSEL_FEED
61+
- `examples/send_bms_free_premium_video.php` — BMS FREE PREMIUM_VIDEO
62+
- `examples/send_bms_free_wide_item_list.php` — BMS FREE WIDE_ITEM_LIST
2863

2964
## Opening Issues
3065

‎examples/get_balance.php‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
use Nurigo\Solapi\Services\SolapiMessageService;
4+
5+
require_once dirname(__DIR__) . '/vendor/autoload.php';
6+
7+
/**
8+
* 충전 요금 조회 예제
9+
*/
10+
$messageService = new SolapiMessageService("ENTER_YOUR_API_KEY", "ENTER_YOUR_API_SECRET");
11+
$response = $messageService->getBalance();
12+
13+
// 충전 요금(잔액) 조회
14+
echo $response->balance . "\n";
15+
16+
// 잔여 포인트 조회
17+
echo $response->point . "\n";

‎examples/get_messages.php‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<?php
2+
3+
use Nurigo\Solapi\Models\Request\GetMessagesRequest;
4+
use Nurigo\Solapi\Services\SolapiMessageService;
5+
6+
require_once dirname(__DIR__) . '/vendor/autoload.php';
7+
8+
9+
/**
10+
* 메시지(문자, 알림톡 모두 포함) 조회 예제
11+
* 반드시 발신번호/수신번호 형식은 01012345678 형식으로 입력해주셔야 합니다!
12+
*/
13+
$messageService = new SolapiMessageService("ENTER_YOUR_API_KEY", "ENTER_YOUR_API_SECRET");
14+
15+
// 필요한 검색 조건에 따라 주석들을 해제하여 응용해보세요!
16+
$parameter = new GetMessagesRequest();
17+
18+
// 발신번호로 검색
19+
// $parameter->setFrom("발신번호 입력");
20+
21+
// 수신번호로 검색
22+
// $parameter->setTo("수신번호 입력");
23+
24+
// 조회할 건 수 지정
25+
// $parameter->setLimit(1);
26+
27+
// 메시지 조회 시 나오는 nextKey로 페이지 조회
28+
// $parameter->setStartKey("nextKey로 나온 값 입력");
29+
30+
// 그룹 ID로 조회
31+
// $parameter->setGroupId("그룹 ID 입력");
32+
33+
// 메시지 ID로 조회
34+
// $parameter->setMessageId("메시지 ID 입력");
35+
36+
// 메시지 ID 여러개 조회
37+
// $parameter->setMessageIds([
38+
// "메시지 ID 입력",
39+
// "메시지 ID 입력"
40+
// ]);
41+
42+
// 메시지 유형(알림톡: ATA, 단문 문자:SMS 등)으로 검색
43+
// 유형에 대한 값은 아래 내용을 참고해주세요!
44+
// SMS: 단문
45+
// LMS: 장문
46+
// MMS: 사진문자
47+
// ATA: 알림톡
48+
// CTA: 친구톡
49+
// CTI: 이미지 친구톡
50+
// NSA: 네이버 스마트알림
51+
// RCS_SMS: RCS 단문
52+
// RCS_LMS: RCS 장문
53+
// RCS_MMS: RCS 사진문자
54+
// RCS_TPL: RCS 템플릿문자
55+
// $parameter->setType("조회 할 메시지 유형입력");
56+
57+
// 조회 할 상태코드 입력, 상태 코드 목록은 아래 페이지를 참고해주세요!
58+
// https://developers.solapi.com/references/message-status-codes
59+
// $parameter->setStatusCode("조회 할 상태코드 입력");
60+
61+
// 날짜로 검색, startDate와 endDate가 반드시 같이 기입되어야 합니다!
62+
// date_default_timezone_set("Asia/Seoul");
63+
// $startDate = DateTime::createFromFormat("Y-m-d H:i:s", "2022-11-22 00:00:00")->format("c");
64+
// $endDate = DateTime::createFromFormat("Y-m-d H:i:s", "2022-11-22 23:59:59")->format("c");
65+
// $parameter->setStartDate($startDate);
66+
// $parameter->setEndDate($endDate);
67+
68+
$messages = $messageService->getMessages($parameter);
69+
print_r($messages);
70+
71+
foreach ($messages->messageList as $key => $val) {
72+
echo "메시지ID: {$val->messageId}\n";
73+
echo "그룹ID: {$val->groupId}\n";
74+
echo "타입: {$val->type}\n";
75+
echo "국가: {$val->country}\n";
76+
echo "제목(LMS, MMS): {$val->subject}\n";
77+
echo "내용: {$val->text}\n";
78+
echo "발신번호: {$val->from}\n";
79+
echo "수신번호: {$val->to}\n";
80+
echo "상태(코드): {$val->statusCode}\n";
81+
echo "-----------------------------\n";
82+
}

‎examples/get_statistics.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?php
2+
3+
use Nurigo\Solapi\Models\Request\GetStatisticsRequest;
4+
use Nurigo\Solapi\Services\SolapiMessageService;
5+
6+
require_once dirname(__DIR__) . '/vendor/autoload.php';
7+
8+
/**
9+
* 충전 요금 조회 예제
10+
*/
11+
$messageService = new SolapiMessageService("ENTER_YOUR_API_KEY", "ENTER_YOUR_API_SECRET");
12+
13+
// 날짜 검색이 필요할 경우 아래 주석을 해제하여 검색해보세요!
14+
$parameter = new GetStatisticsRequest();
15+
16+
// 날짜로 검색, startDate와 endDate가 반드시 같이 기입되어야 합니다!
17+
// date_default_timezone_set("Asia/Seoul");
18+
// $startDate = DateTime::createFromFormat("Y-m-d H:i:s", "2022-11-22 00:00:00")->format("c");
19+
// $endDate = DateTime::createFromFormat("Y-m-d H:i:s", "2022-11-22 23:59:59")->format("c");
20+
// $parameter->setStartDate($startDate);
21+
// $parameter->setEndDate($endDate);
22+
23+
$response = $messageService->getStatistics($parameter);
24+
print_r($response);

‎examples/images/example-1to1.jpg‎

36.6 KB
Loading

‎examples/images/example-2to1.jpg‎

45.4 KB
Loading

‎examples/images/example.jpg‎

60.5 KB
Loading

‎examples/send_alimtalk.php‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
2+
<?php
3+
4+
require_once dirname(__DIR__) . '/vendor/autoload.php';
5+
6+
use Nurigo\Solapi\Exceptions\MessageNotReceivedException;
7+
use Nurigo\Solapi\Models\Kakao\KakaoOption;
8+
use Nurigo\Solapi\Models\Message;
9+
use Nurigo\Solapi\Services\SolapiMessageService;
10+
11+
/**
12+
* 카카오 알림톡(이미지 알림톡 포함, 이미지 알림톡은 별도의 추가 파라미터가 없습니다) 발송 예제
13+
* 수신번호에 반드시 -, * 등 특수문자를 제거하여 기입하셔야 합니다! 예) 01012345678
14+
*/
15+
try {
16+
$messageService = new SolapiMessageService("ENTER_YOUR_API_KEY", "ENTER_YOUR_API_SECRET");
17+
18+
$kakaoOption = new KakaoOption();
19+
$kakaoOption->setPfId("연동한 비즈니스 채널의 pfId")
20+
->setTemplateId("등록한 알림톡 템플릿의 ID");
21+
22+
// 치환문구가 있는 경우에만 추가해주세요, 반드시 키 값은 등록하신 치환문구와 동일하게 모두 입력하셔야 합니다!
23+
// 또한 치환문구 상 키, 값은 모두 string 타입만 허용됩니다.
24+
/*$variables = [
25+
"#{변수명}" => "임의의 값"
26+
];
27+
$kakaoOption->setVariables($variables);*/
28+
29+
$message = new Message();
30+
$message->setTo("수신번호")
31+
->setKakaoOptions($kakaoOption);
32+
33+
// 문자 대체 발송을 희망하실 경우 계정 내에 등록하신 발신번호를 추가해주세요!
34+
// $message->setFrom("계정에서 등록한 발신번호 입력");
35+
36+
// 한 번에 여러 메시지를 발송할 경우 아래 주석을 해제하고 응용하여 사용해보세요!
37+
/*$message = [$message];
38+
for ($i = 0; $i < 3; $i++) {
39+
$tempMessage = new Message();
40+
$tempMessage->setTo("수신번호")
41+
->setKakaoOptions($kakaoOption);
42+
$message[] = $tempMessage;
43+
}*/
44+
45+
// 예약 발송을 원하시는 경우 아래 주석을 해제하고 응용하여 사용해보세요!
46+
// date_default_timezone_set("Asia/Seoul");
47+
// $dateTime = DateTime::createFromFormat("Y-m-d H:i:s", "2022-11-03 18:00:00");
48+
// $result = $messageService->send($message, $dateTime);
49+
50+
$result = $messageService->send($message);
51+
print_r($result);
52+
} catch (MessageNotReceivedException $exception) {
53+
print_r($exception->getFailedMessageList());
54+
print_r("----");
55+
print_r($exception->getMessage());
56+
} catch (Exception $exception) {
57+
print_r($exception->getMessage());
58+
}

‎examples/send_bms_free_carousel_feed.php‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<?php
2+
3+
/**
4+
* BMS 자유형 CAROUSEL_FEED 타입 발송 예제
5+
* 여러 카드를 좌우로 슬라이드하는 캐러셀 피드 메시지입니다.
6+
* fileType은 'BMS_CAROUSEL_FEED_LIST'를 사용해야 합니다 (2:1 비율 이미지 필수).
7+
* head 없이 2-6개 아이템, head 포함 시 1-5개 아이템이 가능합니다.
8+
*/
9+
10+
require_once dirname(__DIR__) . '/vendor/autoload.php';
11+
12+
use Nurigo\Solapi\Models\Kakao\Bms\BmsButton;
13+
use Nurigo\Solapi\Models\Kakao\Bms\BmsCarousel;
14+
use Nurigo\Solapi\Models\Kakao\Bms\BmsCarouselFeedItem;
15+
use Nurigo\Solapi\Models\Kakao\Bms\BmsCarouselTail;
16+
use Nurigo\Solapi\Models\Kakao\Bms\BmsChatBubbleType;
17+
use Nurigo\Solapi\Models\Kakao\KakaoBms;
18+
use Nurigo\Solapi\Models\Kakao\KakaoOption;
19+
use Nurigo\Solapi\Models\Message;
20+
use Nurigo\Solapi\Services\SolapiMessageService;
21+
22+
$messageService = new SolapiMessageService('ENTER_YOUR_API_KEY', 'ENTER_YOUR_API_SECRET');
23+
24+
$imageId = $messageService->uploadFile(__DIR__ . '/images/example-2to1.jpg', 'BMS_CAROUSEL_FEED_LIST');
25+
26+
$button1 = new BmsButton();
27+
$button1->setLinkType('WL')
28+
->setName('레시피 보기')
29+
->setLinkMobile('https://example.com/recipe1');
30+
31+
$item1 = new BmsCarouselFeedItem();
32+
$item1->setHeader('오늘의 브런치 레시피')
33+
->setContent('15분 만에 완성하는 아보카도 토스트! 간단하지만 영양 만점이에요.')
34+
->setImageId($imageId)
35+
->setButtons([$button1]);
36+
37+
$button2 = new BmsButton();
38+
$button2->setLinkType('WL')
39+
->setName('영상 보기')
40+
->setLinkMobile('https://example.com/recipe2');
41+
42+
$item2 = new BmsCarouselFeedItem();
43+
$item2->setHeader('홈카페 꿀팁')
44+
->setContent('집에서 바리스타처럼! 라떼 아트 도전해보세요.')
45+
->setImageId($imageId)
46+
->setButtons([$button2]);
47+
48+
$tail = new BmsCarouselTail();
49+
$tail->setLinkMobile('https://example.com/more');
50+
51+
$carousel = new BmsCarousel();
52+
$carousel->setList([$item1, $item2])
53+
->setTail($tail);
54+
55+
$bms = new KakaoBms();
56+
$bms->setTargeting('I')
57+
->setChatBubbleType(BmsChatBubbleType::CAROUSEL_FEED)
58+
->setCarousel($carousel);
59+
60+
$kakaoOption = new KakaoOption();
61+
$kakaoOption->setPfId('연동한 비즈니스 채널의 pfId')
62+
->setBms($bms);
63+
64+
$message = new Message();
65+
$message->setTo('수신번호')
66+
->setFrom('발신번호')
67+
->setType('BMS_FREE')
68+
->setKakaoOptions($kakaoOption);
69+
70+
try {
71+
$response = $messageService->send($message);
72+
print_r($response);
73+
} catch (Exception $e) {
74+
echo "Error: " . $e->getMessage();
75+
}

‎examples/send_bms_free_commerce.php‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
<?php
2+
3+
/**
4+
* BMS 자유형 COMMERCE 타입 발송 예제
5+
* 상품 정보와 가격을 포함한 커머스 메시지입니다.
6+
* imageId, commerce, buttons가 필수입니다.
7+
*
8+
* 가격 조합 규칙:
9+
* 1. regularPrice만 사용 (정가만 표기)
10+
* 2. regularPrice + discountPrice + discountRate (할인율 표기)
11+
* 3. regularPrice + discountPrice + discountFixed (정액 할인 표기)
12+
*/
13+
14+
require_once dirname(__DIR__) . '/vendor/autoload.php';
15+
16+
use Nurigo\Solapi\Models\Kakao\Bms\BmsButton;
17+
use Nurigo\Solapi\Models\Kakao\Bms\BmsChatBubbleType;
18+
use Nurigo\Solapi\Models\Kakao\Bms\BmsCommerce;
19+
use Nurigo\Solapi\Models\Kakao\Bms\BmsCoupon;
20+
use Nurigo\Solapi\Models\Kakao\KakaoBms;
21+
use Nurigo\Solapi\Models\Kakao\KakaoOption;
22+
use Nurigo\Solapi\Models\Message;
23+
use Nurigo\Solapi\Services\SolapiMessageService;
24+
25+
$messageService = new SolapiMessageService('ENTER_YOUR_API_KEY', 'ENTER_YOUR_API_SECRET');
26+
27+
$imageId = $messageService->uploadFile(__DIR__ . '/images/example.jpg', 'BMS');
28+
29+
$commerce = new BmsCommerce();
30+
$commerce->setTitle('프리미엄 블루투스 스피커')
31+
->setRegularPrice(129000)
32+
->setDiscountPrice(99000)
33+
->setDiscountRate(23);
34+
35+
$buyButton = new BmsButton();
36+
$buyButton->setLinkType('WL')
37+
->setName('지금 구매하기')
38+
->setLinkMobile('https://example.com/buy');
39+
40+
$coupon = new BmsCoupon();
41+
$coupon->setTitle('10000원 할인 쿠폰')
42+
->setDescription('첫 구매 고객 전용 쿠폰입니다.')
43+
->setLinkMobile('https://example.com/coupon');
44+
45+
$bms = new KakaoBms();
46+
$bms->setTargeting('I')
47+
->setChatBubbleType(BmsChatBubbleType::COMMERCE)
48+
->setImageId($imageId)
49+
->setCommerce($commerce)
50+
->setButtons([$buyButton])
51+
->setCoupon($coupon)
52+
->setAdditionalContent('무료배송 | 오늘 주문 시 내일 도착');
53+
54+
$kakaoOption = new KakaoOption();
55+
$kakaoOption->setPfId('연동한 비즈니스 채널의 pfId')
56+
->setBms($bms);
57+
58+
$message = new Message();
59+
$message->setTo('수신번호')
60+
->setFrom('발신번호')
61+
->setType('BMS_FREE')
62+
->setKakaoOptions($kakaoOption);
63+
64+
try {
65+
$response = $messageService->send($message);
66+
print_r($response);
67+
} catch (Exception $e) {
68+
echo "Error: " . $e->getMessage();
69+
}

0 commit comments

Comments
 (0)