sendgo 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a89b23db406e7ccf7ab1fe29fe9cfb2ddb5508cc7ce0367731cdbb5e3153c01f
-  data.tar.gz: bc4763817d9e59830e69e6547d406240b910727476c676cac88233fc431ee0cc
+  metadata.gz: f9c4b04d7a030a8e34230298a109a86571e7089878dd0d5bb8d8bd07a519aeba
+  data.tar.gz: 94b0e1785aac53f05b32cd211901cba951564f4139ad6df7a32684dee559a96a
 SHA512:
-  metadata.gz: 5eb5c76e420bf0f4fb5e6b73db72480c5859077ff3b6288be19a89dec37a5275f7589d7f92a8a3ada0d36bb065e1c2cf477d8613e82468bfb5e1d2bd7ac19bd1
-  data.tar.gz: 428977e7d3d037a17cf20b7c22cb4785cce578abd1766fa5db76a6c1fdb658e33181e213d589f9e6067002c2ac3525c1b7ccb2e6ef836440158dc7cddd8beca2
+  metadata.gz: 5a68d90dc67ee4ef919978e47dae16609431b8f18ce18240eba2427f6ac1023b2aeda677072a571f1006881df9d65fdfa98aec95a96a0f3a813792db8b473b6b
+  data.tar.gz: e6d730f1f9e01db94024083f1f9fb47bbb7954c1809f479f91ec7308bb2df3e2bab56e6291559185a400955f4a066c8bc68fa769b25422cc426b531e0b465b61

data/README.md

@@ -125,6 +125,42 @@ client.friendtalk.send(
 
 ---
 
+## 브랜드메시지 사용법
+
+브랜드메시지는 친구톡의 후속 채널입니다. 메시지 타입이 친구톡과 1:1 대응되며
+(`FT`→`BT`, `FI`→`BI`, `FW`→`BW`, `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`),
+요청에는 **친구톡 코드를 그대로** 넘기고 변환은 서버가 처리합니다.
+
+친구톡과 달리 다음이 가능합니다.
+
+- 채널 친구가 **아닌** 수신자에게 발송 (`targeting: N`)
+- 수신 동의한 **전체 채널 친구 동보** 발송 (`targeting: F`, 수신자 목록 불필요)
+- 리스트·캐러셀·커머스·동영상 등 **템플릿 기반 리치 메시지**
+
+> v2 전용입니다. `FT`/`FI`/`FW`를 채널 친구에게만 보낼 때는 친구톡 API가 더 간단합니다.
+
+```ruby
+# 단건 발송 — 채널 친구 대상
+client.brand_message.send(
+  targeting: "M",
+  message_type: "FL",
+  friend_template_uuid: "9cd5460b-6458-4edc-9b11-c26d3013c340",
+  contacts: [{ contact: "01012345678", var1: "29,000원" }]
+)
+
+# 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+client.brand_message.broadcast(
+  message_type: "FW",
+  friend_template_uuid: "9cd5460b-6458-4edc-9b11-c26d3013c340"
+)
+
+# 캠페인 조회
+campaigns = client.brand_message.campaigns(from: "2026-08-01", count: 10)
+one = client.brand_message.campaign("1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11")
+```
+
+---
+
 ## SMS / LMS / MMS 사용법
 
 ```ruby

data/lib/sendgo/brand_message.rb

@@ -0,0 +1,106 @@
+module Sendgo
+  # 카카오 브랜드메시지 전송 서비스.
+  #
+  # 브랜드메시지는 친구톡의 후속 채널로, 메시지 타입이 친구톡과 1:1 대응된다
+  # (FT→BT, FI→BI, FW→BW, FL→BL, FC→BC, FM→BM, FP→BP, FA→BA).
+  # +message_type+ 에는 친구톡 코드를 그대로 넘기고, 변환은 서버가 처리한다.
+  #
+  # 친구톡과 달리 채널 친구가 아닌 수신자에게도 보낼 수 있고(+targeting: "N"+),
+  # 수신 동의한 전체 채널 친구에게 동보 발송할 수 있다(+targeting: "F"+).
+  #
+  # @example 단건 발송 — 채널 친구 대상
+  #   client.brand_message.send(
+  #     targeting: "M",
+  #     message_type: "FL",
+  #     friend_template_uuid: "9cd5460b-6458-4edc-9b11-c26d3013c340",
+  #     contacts: [{ contact: "01012345678", var1: "29,000원" }]
+  #   )
+  #
+  # @example 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+  #   client.brand_message.broadcast(
+  #     message_type: "FW",
+  #     friend_template_uuid: "9cd5460b-6458-4edc-9b11-c26d3013c340"
+  #   )
+  class BrandMessageService
+    def initialize(http:, kakao_sender_key:, sms_sender_key:)
+      @http             = http
+      @kakao_sender_key = kakao_sender_key
+      @sms_sender_key   = sms_sender_key
+    end
+
+    # 브랜드메시지를 전송한다.
+    #
+    # +targeting+ 이 "M"/"N"/"I" 이면 +contacts+ 가 필요하고 응답 data 에
+    # 발송 건수(sentCount)가 담긴다. "F" 는 동보 발송이라 +contacts+ 없이
+    # 접수 여부(accepted)만 반환되므로, 그 경우 #broadcast 가 더 명확하다.
+    #
+    # +list+ 는 캐러셀 리스트(BC/BA)이며 요청에는 그대로 list 로 전송된다.
+    def send(friend_template_uuid:, message_type: "FT", targeting: "M",
+             contacts: nil, content: nil, schedule_type: "DIRECTLY", at: nil,
+             buttons: [], image_url: nil, image_link: nil,
+             ad_flag: "Y", adult: "N", push_alarm: "Y", header: nil,
+             coupon: nil, item: nil, commerce: nil, list: nil,
+             head: nil, tail: nil, video: nil, additional_content: nil,
+             friend_group_key: nil, replace_sms: "N",
+             sms_subject: nil, sms_content: nil,
+             reject_service_id: nil, webhooks: [])
+      body = {
+        at: at,
+        scheduleType: schedule_type,
+        targeting: targeting,
+        messageType: message_type,
+        friendTemplateUuid: friend_template_uuid,
+        content: content,
+        buttons: buttons,
+        imageUrl: image_url,
+        imageLink: image_link,
+        adFlag: ad_flag,
+        adult: adult,
+        pushAlarm: push_alarm,
+        header: header,
+        coupon: coupon,
+        item: item,
+        commerce: commerce,
+        list: list,
+        head: head,
+        tail: tail,
+        video: video,
+        additionalContent: additional_content,
+        friendGroupKey: friend_group_key,
+        replaceSms: replace_sms,
+        smsSubject: replace_sms == "Y" ? sms_subject : nil,
+        smsContent: replace_sms == "Y" ? sms_content : nil,
+        rejectServiceId: reject_service_id,
+        webhooks: webhooks,
+        kakaoSenderKey: @kakao_sender_key,
+        senderKey: @sms_sender_key,
+      }
+
+      # 동보는 수신자 목록이 없다. 빈 배열을 보내면 잘못된 요청으로 거절되므로
+      # 키 자체를 넣지 않는다.
+      body[:contacts] = contacts || [] unless targeting == "F"
+
+      @http.post("brand-messages/send", body)
+    end
+
+    # 동보 발송 — 수신 동의한 전체 채널 친구 (+targeting: "F"+).
+    #
+    # 수신자 목록은 카카오 측에서 확장하므로 +contacts+ 를 넘기지 않는다.
+    # 결과는 #campaigns / #campaign 으로 확인한다.
+    def broadcast(**kwargs)
+      kwargs.delete(:contacts)
+      send(**kwargs, targeting: "F")
+    end
+
+    # 브랜드메시지 캠페인 목록을 조회한다.
+    def campaigns(from: nil, to: nil, count: nil)
+      @http.get("brand-messages", { from: from, to: to, count: count })
+    end
+
+    # 브랜드메시지 캠페인 상세를 조회한다.
+    # +campaign_id+ 는 발송 응답의 campaignId (UUID).
+    def campaign(campaign_id)
+      @http.get("brand-messages/#{campaign_id}")
+    end
+  end
+end

data/lib/sendgo/client.rb

@@ -10,7 +10,8 @@ module Sendgo
   #     api_version: "v2"
   #   )
   class Client
-    attr_reader :alimtalk, :friendtalk, :sms
+    # brand_message: 카카오 브랜드메시지 — 친구톡의 후속 채널. v2 전용.
+    attr_reader :alimtalk, :friendtalk, :brand_message, :short_url, :sms
 
     def initialize(access_key:, secret_key:, kakao_sender_key: nil, sms_sender_key: nil,
                    api_version: "v1", base_url: "https://sendgo.io")
@@ -22,6 +23,9 @@ module Sendgo
 
       @alimtalk   = AlimtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
       @friendtalk = FriendtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
+      @brand_message = BrandMessageService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
+      # 짧은 URL — 링크 단축과 클릭 반응 분석. v2 전용.
+      @short_url  = ShortUrlService.new(http: http)
       @sms        = SmsService.new(http: http, sms_sender_key: sms_sender_key)
     end
   end

data/lib/sendgo/http_client.rb

@@ -12,21 +12,46 @@ module Sendgo
     end
 
     def post(path, body)
-      do_post(path, body, is_retry: false)
+      request(:post, path, body: body, is_retry: false)
+    end
+
+    # GET 요청. 캠페인 조회 엔드포인트에서 사용한다.
+    # params 의 nil 값은 제외되어 서버 기본값이 적용된다.
+    def get(path, params = {})
+      request(:get, path, params: params, is_retry: false)
+    end
+
+    # DELETE 요청. 짧은 URL 리다이렉트 중지에서 사용한다.
+    def delete(path)
+      request(:delete, path, is_retry: false)
     end
 
     private
 
-    def do_post(path, body, is_retry: false)
-      token  = @token_manager.get_token
-      url    = "#{@base_url}/api/#{@api_version}/#{path}"
-      uri    = URI(url)
-      payload = body.to_json
+    def request(method, path, body: nil, params: nil, is_retry: false)
+      token = @token_manager.get_token
+      url   = "#{@base_url}/api/#{@api_version}/#{path}"
+      uri   = URI(url)
 
-      req = Net::HTTP::Post.new(uri)
-      req["Content-Type"]  = "application/json"
+      if params && !params.empty?
+        query = params.reject { |_, v| v.nil? }
+        uri.query = URI.encode_www_form(query) unless query.empty?
+      end
+
+      req =
+        case method
+        when :get
+          Net::HTTP::Get.new(uri)
+        when :delete
+          # 바디 없는 DELETE. Post 분기로 흘러가면 조용히 POST 로 나간다.
+          Net::HTTP::Delete.new(uri)
+        else
+          Net::HTTP::Post.new(uri).tap do |r|
+            r["Content-Type"] = "application/json"
+            r.body = body.to_json
+          end
+        end
       req["Authorization"] = bearer_auth(token)
-      req.body = payload
 
       resp = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
                              read_timeout: 15, open_timeout: 10) { |h| h.request(req) }
@@ -38,7 +63,7 @@ module Sendgo
         endpoint   = path.split("/").last
         if !is_retry && @token_manager.should_refresh?(resp.code.to_i, error_code)
           @token_manager.invalidate
-          return do_post(path, body, is_retry: true)
+          return request(method, path, body: body, params: params, is_retry: true)
         end
         raise SendgoError.from_response(resp.code.to_i, resp_body, endpoint, @api_version)
       end

data/lib/sendgo/short_url.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Sendgo
+  # 짧은 URL — 메시지에 넣는 링크를 줄이고 클릭 반응을 집계한다.
+  #
+  # v2 전용이다.
+  #
+  # @example
+  #   created = client.short_url.create(
+  #     target_url: "https://example.com/promotions/summer-sale",
+  #     title: "여름 세일 랜딩"
+  #   )
+  #
+  #   # created.dig("data", "shortUrl") 를 문자/알림톡 본문에 넣는다.
+  #   stats = client.short_url.stats(created.dig("data", "code"))
+  class ShortUrlService
+    def initialize(http:)
+      @http = http
+    end
+
+    # 짧은 URL 을 만든다.
+    #
+    # 같은 원본 URL 을 다시 줄이면 기존 링크가 그대로 반환된다.
+    # 캠페인별로 반응을 분리해 집계하려면 +force_new: true+ 를 쓴다.
+    def create(target_url:, title: nil, expires_at: nil, force_new: false)
+      body = { targetUrl: target_url, forceNew: force_new }
+      body[:title] = title unless title.nil?
+      body[:expiresAt] = expires_at unless expires_at.nil?
+
+      @http.post("short-urls", body)
+    end
+
+    # 목록 조회.
+    def list(from: nil, to: nil, count: nil)
+      @http.get("short-urls", { from: from, to: to, count: count })
+    end
+
+    # 상세 조회.
+    def show(code)
+      @http.get("short-urls/#{escape(code)}")
+    end
+
+    # 반응 통계. 일별 추이와 디바이스/유입경로/국가별 분해를 반환한다.
+    def stats(code, from: nil, to: nil)
+      @http.get("short-urls/#{escape(code)}/stats", { from: from, to: to })
+    end
+
+    # 리다이렉트를 중지한다. 링크는 삭제되지 않고 누적 통계도 남는다.
+    # 이후 그 링크로 들어오면 410 Gone 이 반환된다.
+    def deactivate(code)
+      @http.delete("short-urls/#{escape(code)}")
+    end
+
+    private
+
+    def escape(code)
+      CGI.escape(code.to_s)
+    end
+  end
+end

data/lib/sendgo/version.rb

@@ -1,3 +1,3 @@
 module Sendgo
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/sendgo.rb

@@ -4,6 +4,8 @@ require_relative "sendgo/token_manager"
 require_relative "sendgo/http_client"
 require_relative "sendgo/alimtalk"
 require_relative "sendgo/friendtalk"
+require_relative "sendgo/brand_message"
+require_relative "sendgo/short_url"
 require_relative "sendgo/sms"
 require_relative "sendgo/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendgo
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Sendgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies: []
 description: Sendgo API를 Ruby에서 간편하게 사용하기 위한 공식 SDK
 email:
@@ -20,10 +20,12 @@ files:
 - README.md
 - lib/sendgo.rb
 - lib/sendgo/alimtalk.rb
+- lib/sendgo/brand_message.rb
 - lib/sendgo/client.rb
 - lib/sendgo/error.rb
 - lib/sendgo/friendtalk.rb
 - lib/sendgo/http_client.rb
+- lib/sendgo/short_url.rb
 - lib/sendgo/sms.rb
 - lib/sendgo/token_manager.rb
 - lib/sendgo/version.rb