카카오 알림톡 및 음성 메시지 발송 예제 추가, VoiceOption 모델에 reply_range와 counselor_number의 상호 배타성 검증 로직 추가

Author: Palbahngmiyine

examples/simple/send_kakao_bms.py

@@ -0,0 +1,41 @@
+from solapi import SolapiMessageService
+from solapi.model import Bms, KakaoOption, RequestMessage
+
+# API 키와 API Secret을 설정합니다
+message_service = SolapiMessageService(
+    api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET"
+)
+
+# 카카오 알림톡 발송을 위한 옵션을 생성합니다.
+kakao_option = KakaoOption(
+    pf_id="계정에 등록된 카카오 비즈니스 채널ID",
+    template_id="계정에 등록된 카카오 브랜드 메시지 템플릿 ID",
+    # 만약에 템플릿에 변수가 있다면 아래와 같이 설정합니다.
+    # 값은 반드시 문자열로 넣어주셔야 합니다!
+    # variables={
+    #   "#{name}": "홍길동",
+    #   "#{age}": "30"
+    # }
+    # 브랜드 메시지 발송 대상자 설정, M, N 타입은 카카오측의 별도 인허가를 받은 대상만 사용할 수 있습니다.
+    # M: 마케팅 수신 동의 대상자 및 카카오 채널 친구
+    # N: 마케팅 수신 동의 대상자 및 카카오 채널 친구는 제외한 대상자
+    # I: 카카오 채널 친구
+    bms=Bms(targeting="M"),
+)
+
+# 단일 메시지를 생성합니다
+message = RequestMessage(
+    from_="발신번호",  # 발신번호 (등록된 발신번호만 사용 가능)
+    to="수신번호",  # 수신번호
+    kakao_options=kakao_option,
+)
+
+# 메시지를 발송합니다
+try:
+    response = message_service.send(message)
+    print("메시지 발송 성공!")
+    print(f"Group ID: {response.group_info.group_id}")
+    print(f"요청한 메시지 개수: {response.group_info.count.total}")
+    print(f"성공한 메시지 개수: {response.group_info.count.registered}")
+except Exception as e:
+    print(f"메시지 발송 실패: {str(e)}")

examples/simple/send_voice_message.py

@@ -0,0 +1,38 @@
+from solapi import SolapiMessageService
+from solapi.model import RequestMessage, VoiceOption
+
+# API 키와 API Secret을 설정합니다
+message_service = SolapiMessageService(
+    api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET"
+)
+
+"""
+단일 메시지를 생성합니다
+header_message를 사용하는 경우, 반드시 아무 버튼이나 눌러야 text 메시지가 재생됩니다.
+text 메시지가 재생된 이후, reply_range에 명시된 번호(1~9) 혹은 counselor_number에 값이 있을 경우 0번을 눌러야 tail_message가 재생됩니다.
+자세한 사항은 아래 링크를 참고해주세요!
+
+https://developers.solapi.com/references/voice
+"""
+message = RequestMessage(
+    from_="발신번호",  # 발신번호 (등록된 발신번호만 사용 가능)
+    to="수신번호",  # 수신번호
+    text="안녕하세요! SOLAPI Python SDK를 사용한 음성 메시지 발송 예제입니다.",
+    voice_options=VoiceOption(
+        voice_type="FEMALE",
+        header_message="안녕하세요!",
+        tail_message="안녕하세요!",
+        reply_range=1,
+    ),
+)
+
+# 메시지를 발송합니다
+try:
+    response = message_service.send(message)
+    print("메시지 발송 성공!")
+    print(f"Group ID: {response.group_info.group_id}")
+    print(f"요청한 메시지 개수: {response.group_info.count.total}")
+    print(f"성공한 메시지 개수: {response.group_info.count.registered_success}")
+    print(f"실패한 메시지 개수: {response.group_info.count.registered_failed}")
+except Exception as e:
+    print(f"메시지 발송 실패: {str(e)}")

solapi/model/__init__.py

@@ -4,6 +4,7 @@
 from .request.kakao.bms import Bms
 from .request.message import Message as RequestMessage
 from .request.send_message_request import SendRequestConfig
+from .request.voice.voice_option import VoiceOption
 from .response.message import Message as ResponseMessage
 
 __all__ = [
@@ -14,4 +15,5 @@
     "GetGroupsRequest",
     "MessageType",
     "Bms",
+    "VoiceOption",
 ]

solapi/model/request/voice/voice_option.py

@@ -1,16 +1,24 @@
 from typing import Literal, Optional
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, model_validator
 from pydantic.alias_generators import to_camel
 
 
 class VoiceOption(BaseModel):
     voice_type: Literal["FEMALE", "MALE"]
     header_message: Optional[str] = None
     tail_message: Optional[str] = None
-    reply_range: Optional[int] = None
+    reply_range: Optional[Literal[1, 2, 3, 4, 5, 6, 7, 8, 9]] = None
     counselor_number: Optional[str] = None
 
+    @model_validator(mode="after")
+    def check_exclusive_fields(self) -> "VoiceOption":
+        if self.reply_range is not None and self.counselor_number is not None:
+            raise ValueError(
+                "reply_range와 counselor_number는 같이 사용할 수 없습니다."
+            )
+        return self
+
     model_config = ConfigDict(
         alias_generator=to_camel,
         populate_by_name=True,